> ## Documentation Index > Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt > Use this file to discover all available pages before exploring further. # Post provisioning requests ## OpenAPI ````yaml /openapi.json post /provisioning-requests openapi: 3.1.1 info: title: Anima API version: 0.1.0 description: >- The Anima API provides programmatic access to unified infrastructure for AI agents: create and manage agents; send and receive email; place phone calls and send/receive SMS and voice; store and retrieve vault credentials; manage agent identity; and configure webhooks for real-time events. Authenticate using a Bearer token or an API key passed via the X-API-Key header. contact: name: Anima Labs url: https://useanima.sh email: support@useanima.sh license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.useanima.sh/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] paths: /provisioning-requests: post: operationId: provisioningRequest.create requestBody: required: true content: application/json: schema: type: object properties: agentId: anyOf: - type: string pattern: ^[0-9a-z]+$ - type: string pattern: ^[cC][^\s-]{8,}$ description: >- Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key. resource: enum: - VAULT - PHONE_NUMBER type: string description: >- Resource being requested: VAULT (encrypted secret storage for this agent) or PHONE_NUMBER (a provisioned number, Starter+ only). reason: type: string minLength: 1 maxLength: 500 description: >- Why the agent needs this, shown verbatim to the owner. Required — an unexplained ask is not a decidable one. options: type: object properties: countryCode: type: string minLength: 2 maxLength: 2 description: 'PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. ''US''' areaCode: type: string pattern: ^\d{3}$ description: >- PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable description: >- Resource-specific options; ignored for resources that take none required: - resource - reason description: >- Ask the organization owner to provision a resource this agent cannot provision itself. responses: '200': description: OK content: application/json: schema: type: object properties: requestId: type: string description: Unique provisioning request identifier agentId: type: string description: Agent the resource would belong to agentName: type: string description: Agent display name, so the owner knows who is asking resource: enum: - VAULT - PHONE_NUMBER - GENERIC type: string description: >- Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything). reason: type: string description: The agent's stated justification status: enum: - PENDING - APPROVED - DECLINED - EXPIRED - CANCELLED type: string description: >- Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent). options: anyOf: - type: object properties: countryCode: type: string minLength: 2 maxLength: 2 description: >- PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US' areaCode: type: string pattern: ^\d{3}$ description: >- PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable description: >- Resource-specific options; ignored for resources that take none - type: 'null' description: Resource-specific options, if any permission: anyOf: - type: object properties: procedurePath: type: string description: >- The master-gated procedure the agent tried to run, dotted — 'agent.delete' readOnly: type: boolean description: >- Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable. argumentPreview: anyOf: - type: object additionalProperties: type: string - type: 'null' description: >- Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'. required: - procedurePath - readOnly - argumentPreview description: >- Present only on a permission request; null on a resource provisioning request - type: 'null' description: >- What the agent was refused, when this request records a permission rather than a resource expiresAt: type: string format: date-time description: When an unanswered request stops being actionable decidedAt: anyOf: - type: string format: date-time - type: 'null' description: When the owner decided; null while PENDING decidedNote: anyOf: - type: string - type: 'null' description: >- The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first provisionedId: anyOf: - type: string - type: 'null' description: >- Id of what approval created (vault identity or phone identity); null unless APPROVED createdAt: type: string format: date-time description: When the agent asked emailSent: type: boolean description: >- Whether the owner was successfully emailed. False means the request is still live and visible in the console — the notification failed, not the request. required: - requestId - agentId - agentName - resource - reason - status - options - permission - expiresAt - decidedAt - decidedNote - provisionedId - createdAt - emailSent description: >- The created request, plus whether the owner notification actually went out '403': description: '403' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: FORBIDDEN status: const: 403 message: type: string default: Agents can only request resources for themselves. data: {} required: - defined - code - status - message - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '404': description: '404' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: NOT_FOUND status: const: 404 message: type: string default: No such agent in this organization. data: {} required: - defined - code - status - message - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '409': description: '409' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: CONFLICT status: const: 409 message: type: string default: >- An identical request is already pending for this agent. data: {} required: - defined - code - status - message - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'API key for programmatic access. Pass as: X-API-Key: ' ````