Intelligence documents

/v1/intelligence is the compiled layer. roasOS writes these documents from the rows that your workspace already holds. It reads five sources: the confirmed brand facts, your most recent brand extraction, your products, your marketing brief and your finished ad analyses.

The compiler does not read your pins. The pins go to the agent through its own tool. Refer to Memory.

Every operation costs 0 credits, the refresh included. The compiler makes no model call.

Refer to Intelligence for the six slugs, their sources and the rules behind them.

Read every document in one call

Use this call to give one agent, or one prompt of your own, everything that roasOS knows.

curl https://api.roasos.com/v1/intelligence/context \
  -H "Authorization: Bearer roasos_sk_..."

{
  "data": {
    "schema_version": "intelligence-context@1",
    "kind": "intelligence_context",
    "documents": [
      {
        "slug": "brand-truth",
        "title": "Brand Truth",
        "version": 3,
        "updated_at": "2026-08-21T10:31:00.000Z",
        "markdown": "# Brand Truth\n\nAcme sells ...",
        "truncated": false
      }
    ],
    "total_characters": 4820,
    "max_characters_per_document": 18000,
    "max_total_characters": 72000
  }
}

The order of the documents is fixed: brand-truth, products, customer-profiles, voice-of-customer, competitors, creative-patterns. A slug with no document is absent from the list.

Two caps bound the answer. One document gives 18,000 characters at most, and the whole call gives 72,000 characters at most. A document that roasOS cut carries truncated: true. total_characters gives the length of the bodies that you received.

This call takes no task parameter. It gives every active document each time.

List the documents

curl https://api.roasos.com/v1/intelligence/documents \
  -H "Authorization: Bearer roasos_sk_..."

{
  "data": [
    {
      "slug": "brand-truth",
      "title": "Brand Truth",
      "description": "What this brand is: the facts a person confirmed, and what the most recent website extraction found.",
      "status": "active",
      "version": 3,
      "summary": "Acme sells a fragrance-free barrier cream for sensitive skin.",
      "last_compiled_at": "2026-08-21T10:31:00.000Z",
      "created_at": "2026-08-19T08:02:00.000Z",
      "updated_at": "2026-08-21T10:31:00.000Z"
    }
  ]
}

The list gives the index, and never a body. Each slug has one fixed title and one fixed description, both from its compiler. summary is one line that says what the document currently holds.

A slug with no source data has no document, so the list holds fewer than six entries while your workspace is new. roasOS writes no stub document.

status reads active or archived. This list gives both. GET /v1/intelligence/context gives the active documents only. No door writes archived in this release, so every compiled document reads active today and the two calls agree.

Read one document

curl https://api.roasos.com/v1/intelligence/documents/brand-truth \
  -H "Authorization: Bearer roasos_sk_..."

The answer adds four fields to the summary above.

Each timestamp is UTC and ends with Z.

Recompile the documents

curl -X POST https://api.roasos.com/v1/intelligence/refresh \
  -H "Authorization: Bearer roasos_sk_..."

{
  "data": {
    "schema_version": "intelligence-refresh@1",
    "kind": "intelligence_refresh",
    "refreshed_at": "2026-08-21T10:31:00.000Z",
    "credits": 0,
    "documents": [
      { "slug": "brand-truth", "version": 3, "changed": true },
      { "slug": "products", "version": 2, "changed": false },
      { "slug": "competitors", "version": null, "changed": false }
    ]
  }
}

The call compiles every slug now. It schedules nothing.

A slug that has no source data reports version: null, even when an older document for that slug is still in your workspace. The refresh does not delete that document. GET /v1/intelligence/documents/{slug} continues to read it, at the version it held before the call.

One slug compiles once at a time. A second refresh that meets a slug already in compilation leaves that slug alone and reports changed: false for it. Read version to see where the document stands.

The compiler is a pure function over your stored rows, so a refresh is free, deterministic and repeatable. Identical inputs write no new version, and the entry says changed: false. Changed inputs write version N+1 and leave every version before it byte for byte as it was.

last_compiled_at moves on every refresh, because the compiler ran. Read version and changed to see whether the document itself changed.

Call a refresh after you change the rows behind a document: a new brand extraction, a new product, a new pin or a new marketing brief. There is no scheduled refresh in this release.

Errors

Both 503 codes publish retryable: false. Each one is a real published shape and not a transient, so a retry loop is the wrong answer to either.

A refresh that stops at one slug leaves every slug before it written. Read GET /v1/intelligence/documents to see where it stopped.

From an agent

The roasOS agent reads the same documents through its own tools. getBrandContext gives it the index, and readIntelligence gives it one body. Refer to Intelligence.

Next

• Fill these documents from your own website: Extract a brand.
• Teach the agent one fact at a time: Memory.