---
title: "Canonical envelope ingress"
method: POST
path: "/v1/canonical"
---

# Canonical envelope ingress

`POST /v1/canonical`

## Request

- Base URL: `https://api.clichefactory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clichefactory.com/v1/canonical`
- Auth: none declared

Accept a canonical envelope (schema_version, operation, scope, resource, payload), normalize, validate payload, and dispatch by operation (inference, training, deployment, artifact).

## Headers

- `X-API-KEY` string, nullable

## Request body

- CanonicalEnvelope: External canonical envelope at API ingress. Strict (extra="forbid"). metadata is open dict. Mutating operations require idempotency_key.
  - `schema_version` '1.0', required
  - `operation` 'inference.extract' | 'training.create_job' | 'training.get_job' | 'training.cancel_job' | 'deployment.activate' | 'deployment.resolve' | 'artifact.get', required: Canonical operations. Mutating ops require idempotency_key.
  - `request_id` string, required
  - `idempotency_key` string, nullable
  - `scope` Scope, required: External scope: tenant_id optional at API ingress.
    - `tenant_id` string, nullable
    - `project_id` string, required
    - `task_id` string, nullable
    - `environment` string
  - `resource` Resource: Resource identifiers. file_uri is canonical S3 only (no presigned URLs).
    - `document_id` string, nullable
    - `artifact_id` string, nullable
    - `config_id` string, nullable
    - `file_uri` string, nullable
  - `payload` object
  - `metadata` object

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/clichefactory/apis/aio-server.md) · [All operations](https://skmtc.dev/clichefactory/apis/aio-server/llms.txt) · [OpenAPI document](https://skmtc.dev/clichefactory/apis/aio-server/revisions/9bd59f9bbb31?raw)