Resource guide

Training is an asynchronous ingestion job

Start with an empty body to train everything already waiting in the workspace inbox, or union that snapshot with ad-hoc inline files, public URLs, and drive-file references. A successful start returns 202 immediately with the job identity; it means the corpus was accepted, not that training has finished.

The gateway owns the long-running job. It moves through honest coarse phases: snapshotting the inbox, training the immutable job corpus, then finalizing the durable record. Poll the job resource until its public state is done or failed; do not hold the start request open. Job status exposes that coarse phase vocabulary directly and does not invent a numeric completion percentage.

Stage large files directly on the workspace VM

Raw training files do not pass through the public API. First create an upload session as an authenticated workspace member. The response supplies the VM base URL, exact upload path, and short-lived values. Append the encoded filename to uploadPath, then send the upload token as Authorization: Bearer … on that PUT request to the VM. The expiration tells you when to mint a new session. The filename is one safe path segment, and the bytes are stored unchanged.

List or delete staged files through the public API when a CLI or server caller should not connect to the VM directly. The list reports each filename and byte count, the shared inbox quota, and whether training is running. Starting a job atomically moves the inbox into that job's snapshot and recreates an empty inbox, so uploads made during training wait safely for the next run. Deletion is unavailable while a job is running.

To stage a public web page without connecting to the VM, post its absolute HTTP or HTTPS URL to the URL-upload endpoint. Duet scrapes the page's main content into a markdown file with inspectable url, title, and scrapedAt frontmatter, then stores it through the same inbox quota. Re-adding the same URL replaces the deterministic filename. A source_fetch_failed response distinguishes timeout, malformed_response, and non_2xx details; a full inbox remains a 413 response.

{
  "urls": ["https://example.com/handbook"],
  "driveFiles": ["reports/q2.pdf"],
  "files": [
    {
      "filename": "release-notes.md",
      "content": "# Release notes\n\nThe migration is complete.",
      "encoding": "utf8"
    }
  ]
}

The body is optional. To consume only the staged inbox, send no body at all:

POST /v1/ws/acme/train
Authorization: Bearer duet_sk_…

If the staged inbox and every ad-hoc source are empty, the request fails with 400 empty_corpus. Scraped URLs are carried only in that start request and never leak into the next inbox.

Bound inline material before starting

The start schema keeps inline JSON deliberately small. Large or binary sources belong in the raw upload inbox, while existing workspace files should be named through driveFiles. The gateway copies every accepted source byte-for-byte into one immutable job directory before returning 202.

Records are durable memory, not job output

Jobs describe ingestion work. Records are the durable result and remain available after job history ages out. Each record is a markdown file in the agent's .agents/memories folder. List records to discover their stable slug, fetch one to inspect its synthesized content, and use the update operation for a deliberate human correction. Updating content does not rerun the model or replace the archived source corpus. Deletion removes both the memory file and its private source archive.

A fetched record also reports the sources it was trained from — each archived file's path and byte count, plus the url, title, and scrapedAt of any file that was a scraped page. Reading one source returns the bytes the archive kept, so a caller can inspect exactly what the synthesis saw. Sources appear on a single record and never on the record list: resolving them opens each archived file, which listing many records must not pay for. A record whose archive has been pruned reports hasArchive: false and carries no sources.

Retraining replaces a memory instead of adding one

Restage a record to reload its archived sources into the inbox. That replaces whatever was staged, and each archived URL is re-scraped so a page that changed is picked up; a URL whose fetch fails keeps its archived copy and is named in fellBack, so reloading sources never costs a memory its corpus. Then start a job naming that record's slug as targetSlug, and the run installs over it: the slug, its address, and its archive lifecycle stay the same, and any manual edit to the content is replaced. A targetSlug that does not resolve in the same scope, or that names an inherited record, is refused — tolerating it would create a second memory while reporting the first as replaced. Restaging is unavailable while a job is running, since it clears an inbox that job is reading.

Add and recall one memory directly

Automation that already has a single normalized observation can add it without creating a training job. Direct memory search is a bounded relevance lookup over private observational memory; trained files are already pinned into agent context and are intentionally absent from that search. Use training for source ingestion and synthesis; use direct add/search for already-shaped observations.

Train

29 operations

POST/v1/ws/{workspaceSlug}/train/uploads/session

Mint short-lived credentials for direct uploads to the workspace VM

Scope: workspace_member
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {} }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "vmBaseUrl": { "type": "string", "format": "uri" }, "uploadPath": { "type": "string", "minLength": 1 }, "uploadToken": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "number" } }, "required": [ "vmBaseUrl", "uploadPath", "uploadToken", "expiresAt" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/uploads

List files waiting in the workspace training inbox

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uploadedAt": { "type": "number" }, "url": { "type": "string" } }, "required": [ "filename", "size", "uploadedAt" ], "additionalProperties": false } }, "totalBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "capBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "running": { "type": "boolean" } }, "required": [ "files", "totalBytes", "capBytes", "running" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/train/uploads/url

Scrape a public URL into the workspace training inbox

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uploadedAt": { "type": "number" }, "url": { "type": "string" } }, "required": [ "filename", "size", "uploadedAt" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

DELETE/v1/ws/{workspaceSlug}/train/uploads/{filename}

Remove one file from the workspace training inbox

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/train

Snapshot staged sources and start an asynchronous training job

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "urls": { "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 1 } }, "files": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "encoding": { "default": "utf8", "type": "string", "enum": [ "utf8", "base64" ] } }, "required": [ "filename", "content" ] } }, "driveFiles": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "targetSlug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobId": { "type": "string" }, "job": { "type": "object", "properties": { "jobId": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "snapshotting", "training", "finalizing", "cleanup", "done", "failed" ] }, "error": { "type": "string" }, "sourceFailures": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 2048 }, "code": { "type": "string", "const": "source_fetch_failed" }, "message": { "type": "string", "maxLength": 2048 } }, "required": [ "source", "code", "message" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "jobId", "workspaceId", "userId", "state", "phase", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "jobId", "job" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/records/{slug}/sources/{relPath}

Read one file the training archive kept a copy of

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Raw byte stream
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/train/records/{slug}/restage

Reload a memory's archived sources into the staging inbox, re-scraping its URLs

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {} }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "staged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rescraped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "fellBack": { "type": "array", "items": { "type": "string" } } }, "required": [ "staged", "rescraped", "fellBack" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/memories

Add one durable memory without starting a training job.

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "agent", "system", "api", "import" ] }, "sessionId": { "type": "string" } }, "required": [ "content", "source" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "kind": { "type": "string", "enum": [ "observation", "reflection", "manual", "note" ] }, "source": { "type": "string", "enum": [ "user", "agent", "system", "api", "import" ] }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string" }, "observedDate": { "type": "string" }, "referencedDate": { "type": "string" }, "relativeDate": { "type": "string" }, "timeOfDay": { "type": "string" }, "sessionId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packScore": { "type": "number" }, "relevanceScore": { "type": "number" } }, "required": [ "id", "content", "kind", "source", "priority", "createdAt", "lastUsedAt", "observedDate", "tags" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/memories/search

Search durable memory records by relevance.

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Query: Query parameters JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string", "minLength": 1 }, "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "q" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "kind": { "type": "string", "enum": [ "observation", "reflection", "manual", "note" ] }, "source": { "type": "string", "enum": [ "user", "agent", "system", "api", "import" ] }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string" }, "observedDate": { "type": "string" }, "referencedDate": { "type": "string" }, "relativeDate": { "type": "string" }, "timeOfDay": { "type": "string" }, "sessionId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packScore": { "type": "number" }, "relevanceScore": { "type": "number" } }, "required": [ "id", "content", "kind", "source", "priority", "createdAt", "lastUsedAt", "observedDate", "tags" ], "additionalProperties": false } } }, "required": [ "query", "limit", "results" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/jobs

List recent training jobs newest first

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Query: Query parameters JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "snapshotting", "training", "finalizing", "cleanup", "done", "failed" ] }, "error": { "type": "string" }, "sourceFailures": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 2048 }, "code": { "type": "string", "const": "source_fetch_failed" }, "message": { "type": "string", "maxLength": 2048 } }, "required": [ "source", "code", "message" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "jobId", "workspaceId", "userId", "state", "phase", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "jobs" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/{jobId}

Get the progress and result state of one training job

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "job": { "type": "object", "properties": { "jobId": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "snapshotting", "training", "finalizing", "cleanup", "done", "failed" ] }, "error": { "type": "string" }, "sourceFailures": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 2048 }, "code": { "type": "string", "const": "source_fetch_failed" }, "message": { "type": "string", "maxLength": 2048 } }, "required": [ "source", "code", "message" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "jobId", "workspaceId", "userId", "state", "phase", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "job" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/records

List trained memory records newest first

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "memoryId": { "type": "string", "minLength": 1 }, "archiveId": { "type": "string" }, "store": { "type": "string" }, "inherited": { "type": "boolean" }, "ownerAgentSlug": { "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "observedDate": { "type": "string" }, "headline": { "type": "string" }, "model": { "type": "string" }, "sourceFolder": { "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasArchive": { "type": "boolean" } }, "required": [ "slug", "memoryId", "createdAt", "observedDate", "hasArchive" ], "additionalProperties": false } } }, "required": [ "records" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/agent-memory-counts

List trainable workspace agents and their owned memory counts.

Scope: ws:{workspaceSlug}:memory and ws:{workspaceSlug}:agents
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "counts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "trainableAgents": { "type": "array", "items": { "type": "string" } } }, "required": [ "counts" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/train/records/{slug}

Read one trained memory record and its synthesized content

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "memoryId": { "type": "string", "minLength": 1 }, "archiveId": { "type": "string" }, "store": { "type": "string" }, "inherited": { "type": "boolean" }, "ownerAgentSlug": { "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "observedDate": { "type": "string" }, "headline": { "type": "string" }, "model": { "type": "string" }, "sourceFolder": { "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasArchive": { "type": "boolean" }, "content": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "relPath": { "type": "string", "minLength": 1 }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string" }, "title": { "type": "string" }, "scrapedAt": { "type": "string" } }, "required": [ "relPath", "bytes" ], "additionalProperties": false } } }, "required": [ "slug", "memoryId", "createdAt", "observedDate", "hasArchive", "content" ], "additionalProperties": false } }, "required": [ "record" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

PATCH/v1/ws/{workspaceSlug}/train/records/{slug}

Replace the synthesized content of one trained memory record

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "memoryId": { "type": "string", "minLength": 1 }, "archiveId": { "type": "string" }, "store": { "type": "string" }, "inherited": { "type": "boolean" }, "ownerAgentSlug": { "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "observedDate": { "type": "string" }, "headline": { "type": "string" }, "model": { "type": "string" }, "sourceFolder": { "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasArchive": { "type": "boolean" }, "content": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "relPath": { "type": "string", "minLength": 1 }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string" }, "title": { "type": "string" }, "scrapedAt": { "type": "string" } }, "required": [ "relPath", "bytes" ], "additionalProperties": false } } }, "required": [ "slug", "memoryId", "createdAt", "observedDate", "hasArchive", "content" ], "additionalProperties": false } }, "required": [ "record" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

DELETE/v1/ws/{workspaceSlug}/train/records/{slug}

Delete a trained memory record and its archived corpus

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "slug": { "type": "string" }, "memoryId": { "type": "string" } }, "required": [ "deleted", "slug", "memoryId" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/uploads/session

Mint short-lived credentials for direct uploads to an agent training inbox

Scope: workspace_member
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {} }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "vmBaseUrl": { "type": "string", "format": "uri" }, "uploadPath": { "type": "string", "minLength": 1 }, "uploadToken": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "number" } }, "required": [ "vmBaseUrl", "uploadPath", "uploadToken", "expiresAt" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/uploads

List files waiting in an agent training inbox

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uploadedAt": { "type": "number" }, "url": { "type": "string" } }, "required": [ "filename", "size", "uploadedAt" ], "additionalProperties": false } }, "totalBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "capBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "running": { "type": "boolean" } }, "required": [ "files", "totalBytes", "capBytes", "running" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/uploads/url

Scrape a public URL into an agent training inbox

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uploadedAt": { "type": "number" }, "url": { "type": "string" } }, "required": [ "filename", "size", "uploadedAt" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

DELETE/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/uploads/{filename}

Remove one file from an agent training inbox

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }
Delivery: Standard response
Retry: Declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/train

Snapshot staged sources and start an asynchronous agent training job

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "urls": { "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 1 } }, "files": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "encoding": { "default": "utf8", "type": "string", "enum": [ "utf8", "base64" ] } }, "required": [ "filename", "content" ] } }, "driveFiles": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "targetSlug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobId": { "type": "string" }, "job": { "type": "object", "properties": { "jobId": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "snapshotting", "training", "finalizing", "cleanup", "done", "failed" ] }, "error": { "type": "string" }, "sourceFailures": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 2048 }, "code": { "type": "string", "const": "source_fetch_failed" }, "message": { "type": "string", "maxLength": 2048 } }, "required": [ "source", "code", "message" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "jobId", "workspaceId", "userId", "state", "phase", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "jobId", "job" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/jobs

List recent agent training jobs newest first

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Query: Query parameters JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "snapshotting", "training", "finalizing", "cleanup", "done", "failed" ] }, "error": { "type": "string" }, "sourceFailures": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 2048 }, "code": { "type": "string", "const": "source_fetch_failed" }, "message": { "type": "string", "maxLength": 2048 } }, "required": [ "source", "code", "message" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "jobId", "workspaceId", "userId", "state", "phase", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "jobs" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/{jobId}

Get the progress and result state of one agent training job

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "job": { "type": "object", "properties": { "jobId": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "agentId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "preparing", "snapshotting", "training", "finalizing", "cleanup", "done", "failed" ] }, "error": { "type": "string" }, "sourceFailures": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 2048 }, "code": { "type": "string", "const": "source_fetch_failed" }, "message": { "type": "string", "maxLength": 2048 } }, "required": [ "source", "code", "message" ], "additionalProperties": false } }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } }, "required": [ "jobId", "workspaceId", "userId", "state", "phase", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "job" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/records

List trained agent memory records newest first

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "memoryId": { "type": "string", "minLength": 1 }, "archiveId": { "type": "string" }, "store": { "type": "string" }, "inherited": { "type": "boolean" }, "ownerAgentSlug": { "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "observedDate": { "type": "string" }, "headline": { "type": "string" }, "model": { "type": "string" }, "sourceFolder": { "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasArchive": { "type": "boolean" } }, "required": [ "slug", "memoryId", "createdAt", "observedDate", "hasArchive" ], "additionalProperties": false } } }, "required": [ "records" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/records/{slug}

Read one trained agent memory record and its synthesized content

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "memoryId": { "type": "string", "minLength": 1 }, "archiveId": { "type": "string" }, "store": { "type": "string" }, "inherited": { "type": "boolean" }, "ownerAgentSlug": { "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "observedDate": { "type": "string" }, "headline": { "type": "string" }, "model": { "type": "string" }, "sourceFolder": { "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasArchive": { "type": "boolean" }, "content": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "relPath": { "type": "string", "minLength": 1 }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string" }, "title": { "type": "string" }, "scrapedAt": { "type": "string" } }, "required": [ "relPath", "bytes" ], "additionalProperties": false } } }, "required": [ "slug", "memoryId", "createdAt", "observedDate", "hasArchive", "content" ], "additionalProperties": false } }, "required": [ "record" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

PATCH/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/records/{slug}

Replace the synthesized content of one trained agent memory record

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "memoryId": { "type": "string", "minLength": 1 }, "archiveId": { "type": "string" }, "store": { "type": "string" }, "inherited": { "type": "boolean" }, "ownerAgentSlug": { "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "observedDate": { "type": "string" }, "headline": { "type": "string" }, "model": { "type": "string" }, "sourceFolder": { "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasArchive": { "type": "boolean" }, "content": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "relPath": { "type": "string", "minLength": 1 }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string" }, "title": { "type": "string" }, "scrapedAt": { "type": "string" } }, "required": [ "relPath", "bytes" ], "additionalProperties": false } } }, "required": [ "slug", "memoryId", "createdAt", "observedDate", "hasArchive", "content" ], "additionalProperties": false } }, "required": [ "record" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

DELETE/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/records/{slug}

Delete a trained agent memory record and its archived corpus

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "slug": { "type": "string" }, "memoryId": { "type": "string" } }, "required": [ "deleted", "slug", "memoryId" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent

GET/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/records/{slug}/sources/{relPath}

Read one file an agent memory's training archive kept a copy of

Scope: ws:{workspaceSlug}:memory
Request: No JSON request body
Response: Raw byte stream
Delivery: Standard response
Retry: Not declared idempotent

POST/v1/ws/{workspaceSlug}/agents/{agentSlug}/train/records/{slug}/restage

Reload an agent memory's archived sources into its staging inbox, re-scraping its URLs

Scope: ws:{workspaceSlug}:memory
Request: Request JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {} }
Response: Response JSON schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "staged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rescraped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "fellBack": { "type": "array", "items": { "type": "string" } } }, "required": [ "staged", "rescraped", "fellBack" ], "additionalProperties": false }
Delivery: Standard response
Retry: Not declared idempotent