> ## 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. # Get an approval's status (in-app card) > Poll a single `require_approval` action's status. This backs the inline approval card in the AI chat shell, so it is readable by the requester (the user whose action raised it) as well as by an authorized approver. **How this differs from `/api/approvals/{approvalId}/*`:** these routes are guarded by `requireAuth` only — no `agents:approve` scope is required. `requireAuth` is an alias for `authenticate`, so they accept a first-party session, an API key, a `nex_pat_` token, or an OAuth access token alike. A caller who is neither the requester nor an authorized approver gets `404`, not `403` — approvals are not enumerable by outsiders. ## OpenAPI ````yaml https://api.nexspace365.com/api/openapi.json get /api/ai/actions/{id} 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 Four credentials, all but the first sent as `Authorization: Bearer `: session cookie, JWT bearer, API key (`nex_live_…` / `nex_test_…` / `nex_pat_…`), and OAuth 2.1 access token. AI agents should use an API key or an OAuth token with the 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. MCP is served on its own host — `https://mcp.nexspace365.com`, not the API host. `api.nexspace365.com` rejects `/mcp`, `/mcp/*` and `/.well-known/mcp` with `403 MCP_HOST_NOT_ALLOWED`, and those operations pin the correct host with an operation-level `servers` override. The `/.well-known/oauth-protected-resource*` operations are also tagged MCP but are **not** covered by the host guard — they answer on either host. version: 1.0.0 contact: name: NexSpace email: admin@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: Agents description: Headless agent runs, human-in-the-loop approvals, and automation triggers. - 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 - name: Sandbox description: Sandbox (`nex_test_`) data lifecycle for the same production host - name: Platform description: Version discovery and platform metadata. paths: /api/ai/actions/{id}: get: tags: - Agents summary: Get an approval's status (in-app card) description: | Poll a single `require_approval` action's status. This backs the inline approval card in the AI chat shell, so it is readable by the requester (the user whose action raised it) as well as by an authorized approver. **How this differs from `/api/approvals/{approvalId}/*`:** these routes are guarded by `requireAuth` only — no `agents:approve` scope is required. `requireAuth` is an alias for `authenticate`, so they accept a first-party session, an API key, a `nex_pat_` token, or an OAuth access token alike. A caller who is neither the requester nor an authorized approver gets `404`, not `403` — approvals are not enumerable by outsiders. operationId: getAiActionApproval parameters: - $ref: '#/components/parameters/NexSpaceVersionHeader' - name: id in: path required: true description: Approval id (`ai_action_approvals.id`). schema: type: integer responses: '200': description: Approval status content: application/json: schema: type: object properties: approvalId: type: integer toolName: type: string status: type: string description: '`pending`, `approved`, `rejected`, or `expired`.' executionStatus: type: string nullable: true description: Status of the deferred tool execution after approval. executionResult: type: object additionalProperties: true nullable: true description: Tool result payload, once executed. executionError: type: string nullable: true rejectionReason: type: string nullable: true resolvedAt: type: string format: date-time nullable: true '400': description: Invalid approval id '401': $ref: '#/components/responses/UnauthorizedError' '404': description: >- Approval not found — also returned when the caller is neither the requester nor an authorized approver. security: - bearerAuth: [] - apiKeyAuth: [] components: parameters: NexSpaceVersionHeader: name: NexSpace-Version in: header required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: > Pin the request to a dated API version (e.g. `2026-05-10`). Applied by app-level middleware to every `/api` route (`server/routes/index.ts` → `apiVersionMiddleware`), which echoes the resolved value back in the `NexSpace-Version` response header. Omit to get the latest version. Discover the catalog at `GET /.well-known/api-versions`. responses: UnauthorizedError: description: Missing, invalid, expired, or revoked credential. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: Invalid or revoked API key code: UNAUTHENTICATED suggestion: >- Send a valid `Authorization: Bearer ` (nex_live_/nex_pat_ key, JWT, or OAuth access token). retryable: false schemas: Error: type: object properties: error: type: object properties: message: type: string description: Human-readable error message code: type: string description: Machine-readable error code (e.g. VALIDATION_FAILED, NOT_FOUND) details: type: object description: Structured details (e.g. Zod validation issues) suggestion: type: string description: Hint for agents on how to recover retryable: type: boolean description: Whether the same request might succeed on retry required: - message requestId: type: string description: Correlation ID for logs and Sentry required: - error 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 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.