Public documentation for governed AI labor
SDKs/Governance/Connectors
Arx / Docs / API Response Contract

Documentation

API Response Contract

arxsec-app / API_CONTRACT.md

arxsec-app api API_CONTRACT.md

All JSON API endpoints follow a standardized envelope:

  • Success:
  • { "success": true, "error": null, "data": <payload> }
  • Error:
  • { "success": false, "error": { "code": "...", "message": "...", "details": ..., "request_id": "..." }, "data": null }

Status Codes

  • 200/201/202/204: successful operations
  • 400: malformed request semantics
  • 401: unauthenticated request
  • 403: unauthorized request
  • 404: resource not found
  • 409: conflict
  • 422: schema validation failures
  • 429: rate-limited request
  • 500: unhandled internal error
  • 502/504: upstream dependency failures and timeouts

Validation

  • FastAPI request body, query, and path validation is schema-first via Pydantic models.
  • Validation failures return 422 with error.details.

Compatibility Exceptions

The following endpoints keep protocol-specific response shapes:

  • SAML endpoints (/v1/auth/saml/*) keep XML/redirect wire contracts.
  • SCIM endpoints (/v1/scim/*) keep SCIM-compatible media types and schemas.
  • Interactive webhook callbacks (/integrations/slack/interactions, /v1/webhooks/slack/interactions, /v1/webhooks/teams/interactions) keep provider-required callback payloads.

All other JSON endpoints are normalized through shared contract middleware and global exception handling.