---
title: "Submit a durable asynchronous Formation job"
method: POST
path: "/v1/formation/jobs"
tags: ["memory"]
---

# Submit a durable asynchronous Formation job

`POST /v1/formation/jobs`

## Request

- Base URL: `https://api.contextdb.ai`
- URL: `https://api.contextdb.ai/v1/formation/jobs`
- Auth: HTTP bearer

Durably snapshots and enqueues bounded, PII-processed structured text
turns. The worker returns either encrypted candidates for review or an
idempotent commit result. Audio is not accepted. Poll the Location
resource until the closed status is `succeeded` or `failed`.

## Headers

- `Idempotency-Key` string, required

## Request body

- FormationJobRequest
  - `user_id` string, required: End-user memory partition key. Not an identity assertion.
  - `turns` FormationTurn[], required
    - `speaker` 'user' | 'agent' | 'third_party', required
    - `content` string, required
  - `mode` 'propose' | 'commit'
  - `source_id` string, nullable
  - `max_memories` integer
  - `deadline_seconds` number

## Response `202`

Job durably accepted, or an identical enqueue replayed

- FormationJobSubmission
  - `job_id` string, required
  - `status` 'queued' | 'running' | 'retry_wait' | 'succeeded' | 'failed', required
  - `request_id` string, required

## Other responses

- `400`: Malformed request or failed validation
- `401`: Missing, malformed, unknown, or revoked API key
- `403`: Authenticated but not allowed (entitlement or billing state)
- `409`: The key was reused with a different request, an identical request is still running, or a previous process ended with an ambiguous outcome.
- `413`: Body or batch exceeds the configured cap
- `429`: The client IP/project exceeded its request rate, or the project's idempotency retention capacity is full until older keys expire.
- `503`: Memory or metadata store unreachable

---

[API](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api.md) · [All operations](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/revisions/9e441d2e21a7?raw)