> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Accept a handoff > The receiving side accepts; a closed or expired handoff answers 409. ## OpenAPI ````yaml openapi/en/cell.json POST /v1/handoffs/{handoff_id}/accept openapi: 3.1.0 info: title: Niadra data API version: '1' description: >- Writing, context, history, objects, identity, privacy and governance of one space. Every space has a stable address, with the space and the region in its name. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: The space, which comes in the source key. region: default: us-east-2 description: The region of the space, which also comes in the key. security: [] paths: /v1/handoffs/{handoff_id}/accept: post: tags: - coordination summary: Accept a handoff description: >- The receiving side accepts the handoff. **Authentication.** Source key: `Authorization: Bearer nia_sk_...`. Required scope: `coordinate`. It answers only in a space with the `coordination` feature on (the `features` document); in a space without it, 404. operationId: accept_handoff_v1_handoffs__handoff_id__accept_post parameters: - in: path name: handoff_id required: true schema: title: Handoff Id type: string - in: header name: Idempotency-Key required: true schema: maxLength: 256 minLength: 1 title: Idempotency-Key type: string description: >- Required. Kept 24 hours with the hash of the body: a retry with the same key returns the first answer, and the same key with a different body returns 409 `conflict`. responses: '200': content: application/json: schema: $ref: '#/components/schemas/Handoff' description: The handoff, accepted. '409': description: The handoff was closed or expired. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The request does not match the contract. security: - sourceKey: [] components: schemas: Handoff: additionalProperties: false properties: created_at: format: date-time title: Created At type: string expected_by: anyOf: - format: date-time type: string - type: 'null' title: Expected By handoff_id: maxLength: 512 minLength: 1 title: Handoff Id type: string outcome: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Outcome package: anyOf: - $ref: '#/components/schemas/HandoffPackage' - type: 'null' status: enum: - created - accepted - closed - expired title: Status type: string required: - handoff_id - status - created_at title: Handoff type: object Problem: additionalProperties: false description: RFC 9457 problem details; `code` comes from the versioned error catalog. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object HandoffPackage: additionalProperties: false description: >- What a handoff carries to whoever receives it (the coordination spec, 7). properties: commitments_active: items: $ref: '#/components/schemas/CommitmentRef' title: Commitments Active type: array context: $ref: '#/components/schemas/HandoffContext' created_at: format: date-time title: Created At type: string effects: items: $ref: '#/components/schemas/EffectSeen' title: Effects type: array from_agent: maxLength: 256 minLength: 1 title: From Agent type: string handoff_id: maxLength: 512 minLength: 1 title: Handoff Id type: string level: $ref: '#/components/schemas/Verification' open_objects: items: $ref: '#/components/schemas/OpenObject' maxItems: 50 title: Open Objects type: array outcome: $ref: '#/components/schemas/OutcomeRequest' owner: anyOf: - $ref: '#/components/schemas/Owner' - type: 'null' promises_open: items: $ref: '#/components/schemas/PromiseRef' title: Promises Open type: array reason: anyOf: - maxLength: 500 minLength: 1 type: string - type: 'null' title: Reason spec: const: handoff-package.v0 default: handoff-package.v0 title: Spec type: string subject: anyOf: - $ref: '#/components/schemas/Handle' - type: 'null' description: Whom the handoff is about. suppressions: items: pattern: ^[a-z][a-z0-9_]{0,39}$ type: string title: Suppressions type: array target: maxLength: 256 minLength: 1 title: Target type: string required: - handoff_id - created_at - from_agent - target - level - context title: HandoffPackage type: object CommitmentRef: additionalProperties: false properties: id: maxLength: 512 minLength: 1 title: Id type: string type: pattern: ^[a-z][a-z0-9_]{0,39}$ title: Type type: string valid_until: anyOf: - format: date-time type: string - type: 'null' title: Valid Until required: - id - type title: CommitmentRef type: object HandoffContext: additionalProperties: false description: >- The compiled `handoff` view, at the receiving side's policy and verification level. `etag` is the pack's it was compiled from, absent for a subject the memory knows nothing of yet. properties: etag: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Etag policy_version: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Policy Version text: title: Text type: string required: - text title: HandoffContext type: object EffectSeen: additionalProperties: false properties: effect_id: pattern: ^[A-Za-z0-9_-]{43}$ title: Effect Id type: string kind: $ref: '#/components/schemas/EffectKind' state: enum: - reserved - done - failed - unknown_outcome title: State type: string required: - effect_id - kind - state title: EffectSeen type: object Verification: description: Session verification levels. `no_customer` sits outside the V0-V4 scale. enum: - V0 - V1 - V2 - V3 - V4 - no_customer title: Verification type: string OpenObject: additionalProperties: false properties: ref: $ref: '#/components/schemas/ObjectRef' since: anyOf: - format: date-time type: string - type: 'null' title: Since state: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: State required: - ref title: OpenObject type: object OutcomeRequest: additionalProperties: false description: >- How the receiving side reports back: one of `vocabulary`, by `expected_by`. properties: expected_by: anyOf: - format: date-time type: string - type: 'null' title: Expected By vocabulary: items: pattern: ^[a-z][a-z0-9_]{0,39}$ type: string maxItems: 50 title: Vocabulary type: array title: OutcomeRequest type: object Owner: additionalProperties: false description: >- Who holds the subject or the object now: the most restrictive valid claim, where it came from and until when. `epoch` fences a release. properties: epoch: title: Epoch type: integer holder: maxLength: 256 minLength: 1 title: Holder type: string kind: $ref: '#/components/schemas/ClaimKind' level: pattern: ^[a-z][a-z0-9_]{0,39}$ title: Level type: string since: format: date-time title: Since type: string source: maxLength: 256 minLength: 1 title: Source type: string valid_until: format: date-time title: Valid Until type: string via: $ref: '#/components/schemas/ClaimVia' required: - holder - kind - level - source - via - since - valid_until - epoch title: Owner type: object PromiseRef: additionalProperties: false properties: due: anyOf: - format: date-time type: string - type: 'null' title: Due id: maxLength: 512 minLength: 1 title: Id type: string owner: maxLength: 256 minLength: 1 title: Owner type: string required: - id - owner title: PromiseRef type: object Handle: additionalProperties: false description: >- An identifier of a subject in some channel or system: a phone, an e-mail, a CRM id. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Namespace for scoped identifiers: the WhatsApp Business account for `wa_bsuid`, the system for `system_id`, the country for `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: Defaults to `person`, except for organization-only handle types. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- The identifier. Normalized on the server: E.164 for phones, lowercase for e-mail. required: - type - value title: Handle type: object EffectKind: enum: - delivery - document - notice - filing - paid_call - external_action title: EffectKind type: string ObjectRef: additionalProperties: false description: >- A business object in a system of record, e.g. `invoice` / `erp` / `0823`. properties: id: maxLength: 512 minLength: 1 title: Id type: string description: The id in that system. namespace: maxLength: 256 minLength: 1 title: Namespace type: string description: The system it lives in, such as `erp`. type: maxLength: 256 minLength: 1 title: Type type: string description: Object type, such as `invoice`, `order` or `ticket`. required: - type - namespace - id title: ObjectRef type: object ClaimKind: enum: - owner - case - task_lock title: ClaimKind type: string ClaimVia: description: >- The three ways in: a declaration through the API, an observation mapped from a webhook, an observation the company's worker read and sent. enum: - declaration - mapping - worker title: ClaimVia type: string SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- A person, a customer organization (`account`) or an organization that takes part without being a customer (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- The kind of identifier. The value is classified by its format, never by the field it came from. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````