Send stable source material to /v1/compress and get a persistent handle back, then activate that handle through /v1/context/run for task-specific prompts. Evaluate the handle on your own representative work and route production traffic only after your quality, safety, and operational requirements pass.
Mint a scoped key in the developer console, then create a hosted context handle and activate it. Every request authenticates with Authorization: Bearer <key> and needs the compress:write scope.
export DISTIL_API_KEY="..." # from /developers/keys
BASE="https://dev.primarydesignco.com/api/v1"
# 1 — Create a hosted context handle from stable, reusable source
curl -s "$BASE/compress" \
-H "Authorization: Bearer $DISTIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "<your large, reusable source text>",
"task": "Answer production rollout questions.",
"rubric": ["preserve blockers", "preserve owners", "preserve dates"],
"must_preserve": ["owners", "dates"]
}'
# -> 200 { "data": { "context_handle": "ctx_...", "expires_at": "...", ... },
# "usage": { ... } }
# 2 — Activate the handle for a task. Reuse the same handle across many runs.
curl -s "$BASE/context/run" \
-H "Authorization: Bearer $DISTIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"context_handle": "ctx_...",
"task": "What blocks the next rollout?",
"output_contract": "Answer as a short bulleted list."
}'
# -> 200 { "data": { "answer": "...", "context_handle": "ctx_...", "model": "..." },
# "usage": { ... } }
# 3 — Delete a handle early (optional, no credit charge)
curl -s -X DELETE "$BASE/context/ctx_..." \
-H "Authorization: Bearer $DISTIL_API_KEY"
/v1/compress may return 202 Accepted with data.status_endpoint. Poll GET /v1/compress/jobs/{job_id} until data.status is "completed", then read data.context_handle.Only these fields are honored. Send the names below verbatim — unknown fields are ignored, not errors.
| /v1/compress | Type | Notes |
|---|---|---|
text | string | The reusable source. Or send sources, images, audio, or video. |
sources | array | Mixed document, text, image, audio, or video source records. |
documents / files | array | Convenience arrays for document or text records. |
images | array | Image assets or records used by the approved workflow. |
audio | array | Audio assets or records used by the approved workflow. |
video | object | A video asset or record used by the approved workflow. |
task | string | What the context is being prepared for. (request is also accepted.) |
rubric | string | string[] | Quality criteria the preprocessing must respect. |
must_preserve | string[] | Exact facts that must survive preprocessing. |
| /v1/context/run | Type | Notes |
|---|---|---|
context_handle | string | Required. The ctx_… handle from /compress. |
task | string | Required. The task-specific question. (request and input are also accepted.) |
output_contract | string | Optional. Plain-language output shape, e.g. “Answer as a short bulleted list.” |
style | string | Optional. Tone or voice guidance. |
max_output_tokens | number | Optional. 256–6,000; default 1,600. |
task (input also works); output_contract is a string, not an object; the compress quality list is rubric, not review_criteria.{ "error": { "type", "message" } }.Retry 429 and 5xx with bounded exponential backoff. Do not retry 400, 401, 403, 404, or 422 unchanged.
| Status | error.type | Meaning |
|---|---|---|
| 400 | invalid_request_error | Missing or invalid field (e.g. no task). |
| 401 | authentication_error | Missing, invalid, or revoked API key. |
| 403 | permission_error | Key lacks the compress:write scope. |
| 404 | not_found_error | Handle or job not found for this exact key. |
| 422 | disclosure_policy_error | Task tries to reveal or reconstruct the hosted context. |
| 429 | rate_limit_error | Per-key rolling one-minute limit; honor Retry-After. |
| 502 / 503 | upstream_error / service_unavailable | Transient. Back off and retry. |
Use Distil as a source-preparation layer. Define the job, preserve required facts, create a hosted context handle, then measure quality and cost against the raw-source baseline.
Send a bounded package to /v1/compress, then ask task-specific questions with /v1/context/run.
| Need | Endpoint | Typical output |
|---|---|---|
| Shrink large text, code, docs, records, images, audio, or video assets | /v1/compress | Hosted context handle and account-visible status |
| Run a task against hosted evidence | /v1/context/run | Task-specific output and measured usage |
202 Accepted. Follow the returned public status until the run is complete. Status responses intentionally show coarse progress only.Use this template to define the first production workflow, align stakeholders, prepare the source package, and measure whether Distil improves quality, cost, or throughput.
Choose the closest operating environment so the first workflow uses the right inputs and acceptance checks.
Write the target outcome as a concrete, measurable job.
Define exactly what raw material enters the workflow. A useful source package should be bounded, repeatable, and mapped to the downstream job.
{
"workflow": "priority SKU product-page improvement",
"sources": [
"catalog record",
"recent reviews",
"Q&A",
"return reasons",
"support snippets",
"search queries",
"optional product or shelf images"
],
"refresh": "nightly or when review/return volume crosses threshold",
"max_raw_tokens": 40000,
"owner": "merchandising operations",
"sensitive_fields_to_exclude": ["payment data", "private account identifiers"]
}
Pick the smallest public sequence that supports the job. Distil performs source preparation inside the managed service.
/v1/compress: large source packages, including text, documents, images, audio, and video./v1/context/run: task-specific answers from a hosted context handle.Use task-aware fields so the hosted context supports what the workflow actually needs. The public /v1/compress body accepts text and/or mixed sources; media normalization runs inside the managed Distil pipeline.
{
"text": "<optional source notes>",
"sources": [
{"type": "document", "name": "policy.pdf", "text": "<document text>"},
{"type": "image", "name": "shelf.jpg", "data": "<base64>"},
{"type": "audio", "name": "call.m4a", "data": "<base64>"}
],
"video": {"name": "walkthrough.mp4", "mime": "video/mp4", "data": "<base64>", "duration_seconds": 120},
"task": "Prepare hosted context for the target workflow.",
"rubric": [
"Preserve required facts",
"Separate source facts from interpretation",
"Keep uncertainty visible"
],
"must_preserve": [
"policy limits",
"citations",
"return reasons",
"failure messages",
"customer commitments"
]
}
Define what a usable hosted context must support before another system relies on it. Customer applications store the handle and consume task-specific outputs.
Reuse hosted context handles so the same source material is not processed repeatedly.
context_handle, expires_at, package version, workflow name, and review criteria version.compress:write for /v1/compress, /v1/context/run, and handle deletion.expires_at. Create a new version when sources or the quality contract change.DELETE /v1/context/{context_handle} removes a handle early at no credit charge./v1/context/run runs the requested task against the hosted handle and reports account-visible usage.output_contract, style, and max_output_tokens fields control the task-specific output. Output tokens are bounded from 256 to 6,000 and default to 1,600.Specify where the task output goes after Distil: dashboard, automation, review queue, answer generator, or enterprise tool.
Handoff rules: - Use the task output as the primary context. - Do not invent missing facts. - Preserve uncertainty labels. - Escalate to raw source when exact wording, policy, legal, medical, financial, security, or high-impact details are required.
Define what the workflow should receive from each run. Keep the hosted context behind the handle and return only the task-specific evidence needed for the workflow.
Output rules: - Do not return downloadable hosted context state. - Return only task-necessary facts, uncertainty labels, citations, and actions. - Reject requests that ask to reveal, decode, export, or reconstruct hosted context state. - Log that output validation passed before delivery.
Quality is the gate. A smaller request only matters if the resulting workflow stays reliable enough for production.
{
"required_checks": [
"all must-preserve facts present",
"no unsupported claims",
"citations or source anchors preserved when available",
"uncertainty is labeled",
"output schema validates"
],
"human_review": [
"first 50 production cases",
"all high-impact decisions",
"all low-confidence recognition matches"
],
"fallback": "use the customer-controlled raw-source baseline when the candidate fails the quality contract"
}
Estimate value from the actual workflow, not a generic compression claim.
Instrument the workflow from first request through downstream result.
Minimize source material before it enters any automated workflow.
Confirm the operating contract before production traffic begins.
Expand only after the measured workflow improves.
Choose one source-heavy workflow, run a representative evaluation, then measure quality, latency, and cost against your raw-source baseline.
Start integration