---
title: "Canonical queued-ingest endpoint (Phase 2B, 2026-05-25)."
method: POST
path: "/api/v1/copy-ingest"
tags: ["Copy Ingest"]
---

# Canonical queued-ingest endpoint (Phase 2B, 2026-05-25).

`POST /api/v1/copy-ingest`

## Request

- Base URL: `https://api.avatarfactory.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.avatarfactory.io/api/v1/copy-ingest`
- Auth: one of:
  - API key in cookie `session`
  - HTTP bearer

<br/>Body: { url: "https://instagram.com/reel/..." }<br/><br/>Creates a CopyHistory row in 'queued' state, hands off to the<br/>`run_queued_ingest` Celery task, and returns 202 + the ingest_id<br/>so the frontend can poll GET /api/v1/copy-ingest/history.<br/><br/>Dedupes per (owner, url): re-posting the same URL from the same<br/>user returns the existing row's id with its current status (200,<br/>not 202) so the client's poll loop keeps working.<br/><br/>Worker handoff: the row stays in 'queued' state until the Celery<br/>task picks it up (`app/modules/copy_ingest/tasks.py::run_queued_ingest`).<br/><br/>`level` picks the extraction tier (transcript|scene|full|replica).<br/>'replica' (Clone-a-Reel, 2026-07-10) adds the per-shot source<br/>breakdown used to auto-build a replicated storyboard; re-posting a<br/>URL with a higher level than its existing row upgrades that row<br/>in place.<br/><br/>429 `COPY_INGEST_DAILY_CAP` once the caller has started<br/>`COPY_INGEST_DAILY_CAP` new copies inside the window (20 by default,<br/>admins exempt). A dedupe and a free clone of a ready analysis never<br/>count; see `daily_cap.py`.

## Request body

- IngestBody: Body for the canonical queued-ingest endpoint. Phase 2B (2026-05-25). The Copy From Reel page POSTs a URL here; the row is created with status='queued' and the worker picks it up asynchronously. `level` (2026-07-10, Clone-a-Reel) picks the extraction tier; 'replica' adds the per-shot source breakdown.
  - `level` string
  - `url` string

## Response `200`

OK

- IngestQueuedResponse: 202 payload for POST /api/v1/copy-ingest.
  - `ingest_id` integer, required
  - `status` string, required

## Other responses

- `202`: Accepted
- `400`: Bad Request
- `422`: Unprocessable Entity
- `429`: Too Many Requests

---

[API](https://skmtc.dev/avatarfactory/apis/avatarfactory-api.md) · [All operations](https://skmtc.dev/avatarfactory/apis/avatarfactory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/avatarfactory/apis/avatarfactory-api/revisions/66fc7aa3f296?raw)