> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nexspace365.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reject a pending agent action (and terminate its run)

> Reject a `require_approval` action raised by one of your headless runs.
The deferred tool is NOT executed; a denial note is appended to the run's
conversation and the owning run is terminated with `status: rejected`.
Requires the `agents:approve` scope and ownership of the owning run.
Consequential — writes an audit entry.




## OpenAPI

````yaml https://api.nexspace365.com/api/openapi.json post /api/approvals/{approvalId}/reject
openapi: 3.0.3
info:
  title: NexSpace 365 API
  description: >
    Multi-industry enterprise workforce management platform — scheduling, HR,

    payroll, CRM, AI, and messaging suites.


    ## Authentication

    Three schemes: session cookie, JWT bearer, or API key (`nex_live_…` /

    `nex_test_…` / `nex_pat_…`). AI agents should use API keys with appropriate

    scopes.


    ## Authorization

    Endpoints require specific permissions via the RBAC system:

    - **Internal team**: Full platform access

    - **Facility users**: Scoped to their org/facilities

    - **Staff**: Limited to own data


    ## Error Contract

    All errors return `{ error: { message, code?, suggestion?, retryable? },
    requestId? }`.

    The `suggestion` field hints at how to fix the request; `retryable` signals
    whether

    retry-with-backoff is appropriate.


    ## Versioning

    Pin your integration to a specific API version via the `NexSpace-Version`
    header

    (date-based, e.g. `2026-05-10`). When absent, the latest version is assumed.

    Deprecated versions include `Sunset` and `Deprecation` headers. Discovery at

    `GET /.well-known/api-versions`.


    ## Idempotency

    Write operations (POST/PUT/PATCH) accept an `Idempotency-Key` header. If

    the same key + body combination is sent again within 24 hours, the original

    response is replayed. Different body with the same key returns 409 Conflict.


    ## MCP (Model Context Protocol)

    AI agents interact via `POST /mcp` using JSON-RPC 2.0. Call `tools/list` to

    discover available verbs, then `tools/call` to invoke them.
  version: 1.0.0
  contact:
    name: NexSpace API Support
    email: support@nexspace365.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.nexspace365.com
    description: Production server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Authentication
    description: User authentication and session management
  - name: Facilities
    description: Facility management
  - name: Staff
    description: Staff member management and profiles
  - name: Credentials
    description: Staff credential tracking — licenses, certifications, and training
  - name: Shifts
    description: Shift scheduling and management
  - name: Dashboard
    description: Dashboard statistics and widgets
  - name: API Keys
    description: API key lifecycle — create, list, revoke, rotate
  - name: MCP
    description: Model Context Protocol endpoint for AI agent tool calling
  - name: OAuth
    description: OAuth 2.1 authorization server — DCR, authorize, token
  - name: Webhooks
    description: Outbound webhook subscription management
  - name: Analytics
    description: API usage analytics and observability
paths:
  /api/approvals/{approvalId}/reject:
    post:
      tags:
        - Agents
      summary: Reject a pending agent action (and terminate its run)
      description: >
        Reject a `require_approval` action raised by one of your headless runs.

        The deferred tool is NOT executed; a denial note is appended to the
        run's

        conversation and the owning run is terminated with `status: rejected`.

        Requires the `agents:approve` scope and ownership of the owning run.

        Consequential — writes an audit entry.
      operationId: rejectAgentAction
      parameters:
        - name: approvalId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  maxLength: 2000
      responses:
        '200':
          description: Approval resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalResolution'
        '403':
          description: Credential missing the agents:approve scope
        '404':
          description: >-
            Approval not found, not a headless-run approval, or not owned by the
            credential
        '409':
          description: Approval already resolved
      security:
        - apiKeyAuth: []
components:
  schemas:
    ApprovalResolution:
      type: object
      description: Result of resolving (approving/rejecting) a pending agent action.
      properties:
        outcome:
          type: string
          enum:
            - resolved
        approvalId:
          type: integer
        decision:
          type: string
          enum:
            - approve
            - reject
        runId:
          type: string
          nullable: true
          description: The headless run this approval belongs to.
        runResumed:
          type: boolean
          description: >-
            True when the owning run was re-driven (all its approvals now
            terminal).
        runRejected:
          type: boolean
          description: True when the owning run was terminated as rejected.
        execution:
          type: object
          nullable: true
          description: Outcome of executing the deferred tool (approve only).
          properties:
            success:
              type: boolean
            error:
              type: string
              nullable: true
      required:
        - outcome
        - approvalId
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: NexSpaceApiKey
      description: |
        API key or personal access token (NEX-1042). Send as
        `Authorization: Bearer <token>`. Token format:
          - `nex_live_…`  — live API key (server-to-server)
          - `nex_test_…`  — sandbox API key
          - `nex_pat_…`   — personal access token (acts as the issuing user)

        Authorization is decided by the key's `scopes` array, not the
        owning user's RBAC role. See `POST /api/api-keys` to mint a key.

````