Skip to documentation
Markdown version →

Research

Use saved competitor, market, and public-feedback research with workspace API keys. Read results, review a plan, start research, add saved evidence to Discovery, then choose whether to keep it updated. Read access, permission to run research, and permission to manage updates are separate scopes.

4 endpoints

GET

Find saved research

GET /external/v1/research

Find saved research by name, question, subject, or scope. Returns brief identities, states, row versions, cadence, and next-run times. The body contains items and pagination with total, limit, offset, and hasMore. No model or source-provider calls occur. A failed read is an error, not an empty library.

Requirements

API scopes required:
research:read

Request

Parameters

NameTypeDescription
q stringText search, at most 120 characters.
limit integerPage size, 1–50. Default 10.
offset integerMatching items to skip. Default 0. For run history, use cursor instead.

Responses

200
Success

Saved data or the requested action receipt.

400
Invalid request

Invalid identity, unsupported fields, incomplete command, or invalid plan.

403
Access required

Missing API scope or current workspace role for a write.

404
Not found

The research or run does not belong to this workspace.

409
Review required

Stale plan, incompatible run, unavailable destination, or a schedule that cannot be changed.

Example Request

GET
/external/v1/research
curl
curl 'https://zentrik.ai/api/external/v1/research?q=planning&limit=10' -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK
json
{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Planning tools",
      "state": "draft",
      "rowVersion": 1
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasMore": false
  }
}
GET

Inspect saved research

GET /external/v1/research/:id

Read the editable plan, run progress, dated history, a section’s answer and cited web findings, or original directly read reviews. Use saved run and section IDs for comparisons over time. Compare the original questions, scope, and recorded date windows from view=run rather than the current edited plan. Reads do not start research. brief returns {brief}; progress returns {run}, null when no run exists; run requires runId and returns {run, definition, fromDateTime, toDateTime} from that saved execution, with null dates if not recorded yet; runs returns a keyset page with items, hasMore, and nextCursor; findings returns answer, items, and pagination; records returns items and pagination. Findings keep their source URL, observations, dates, relevance, and provenance. Unknown dates remain unknown. Records are the directly read source items; web sources are in findings. Run receipts omit full snapshots and answers. Back off polling when progress is unchanged.

Requirements

API scopes required:
research:read

Request

Parameters

NameTypeDescription
id *UUIDResearch brief identity from the list (path).
view enumbrief (default), progress, runs, run, findings, or records.
runId UUIDRequired for run, findings, or records. Must belong to this brief.
sectionId UUIDRequired for findings. Use a section identity from the plan or run receipt.
cursor stringThe prior nextCursor for view=runs. At most 1,000 characters.
limit integerPage size, 1–50. Default 10.
offset integerMatching items to skip. Default 0. For run history, use cursor instead.

Responses

200
Success

Saved data or the requested action receipt.

400
Invalid request

Invalid identity, unsupported fields, incomplete command, or invalid plan.

403
Access required

Missing API scope or current workspace role for a write.

404
Not found

The research or run does not belong to this workspace.

409
Review required

Stale plan, incompatible run, unavailable destination, or a schedule that cannot be changed.

Example Request

GET
/external/v1/research/:id
curl
curl 'https://zentrik.ai/api/external/v1/research/11111111-1111-4111-8111-111111111111?view=brief' -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK
json
{
  "brief": {
    "id": "11111111-1111-4111-8111-111111111111",
    "rowVersion": 1,
    "configuration": {
      "state": "draft",
      "draft": {
        "revision": 1,
        "definition": {
          "researchMode": "baseline",
          "maxSourcesPerSection": 3,
          "sections": [
            {
              "id": "22222222-2222-4222-8222-222222222222",
              "type": "market",
              "name": "Planning tools",
              "topic": "Product planning tools",
              "objective": "Understand unmet needs",
              "questions": [
                "Which needs remain unmet?"
              ]
            }
          ]
        }
      }
    }
  }
}
POST

Prepare, run, or deliver research

POST /external/v1/research/run

Choose one action in command.action. prepare drafts a plan from question (8–3,000 characters); review it before start. If apps are ambiguous, continue prepare with preparedPlan from the response and selection [{ connector: "app_store", externalId, label }] from its choices, at most four. start requires requestId (UUID), name (1–120 characters), and definition; editing also requires briefId and expectedRowVersion. Reuse requestId for HTTP retries of the same start request; use a new UUID for an intentional fresh run. start returns briefId and run. add requires briefId, runId, and productId and queues the exact saved sources without a new search. The destination cannot change after addition. retry, retry_addition, and stop require briefId and runId. Retry retains original dates and reusable completed work; stop preserves sealed preview results. Preparation, search, and evidence processing use AI credits. A run receipt confirms queued or completed work; poll progress and read the saved findings before reporting success or adding evidence. The API key’s creator must still be an active member with edit access. Keys with no creator can read but cannot run research.

Requirements

API scopes required:
research:run

Request

Request body (application/json)

commandobject
Required

Exactly one prepare, start, add, retry, retry_addition, or stop command as described above. Unsupported fields are rejected.

command.definitionobject

Required for start. Use a reviewed prepare response or saved draft definition. Only the fields below are accepted. Preparation defaults to three sources per section; a directly supplied definition defaults to five. Set maxSourcesPerSection explicitly to control the target.

command.definition.sectionsobject[]

1–5 sections. Each needs a distinct UUID id, name (1–120 characters), type (competitors, market, or custom), objective (1–1,500 characters), and 1–5 questions (1–500 characters each). competitors sections need 1–5 competitors with name (1–160), optional website, and at most five aliases. market sections need topic (1–500); custom sections can have an optional topic (at most 500).

command.definition.sections[].scopeobject

Optional geography (at most 160 characters), audience (300), exclusions (1,000), languages (1–5 labels, 1–50 each; default English), sourceMode (open, preferred, restricted; default open), domains and excludedDomains (at most 20 each). Preferred and restricted require at least one domain. Excluded domains remain blocked.

command.definition.researchModeenum

recent (default) requires qualifying dates; baseline can retain relevant older or undated sources.

command.definition.initialLookbackDaysinteger

1–90, default 30. Retries preserve their original dates.

command.definition.maxSourcesPerSectioninteger

1–10. Qualifying source target, not guaranteed coverage. First previews use one search round per section.

command.definition.outputLanguagestring

1–50 characters, default English.

command.definition.productIdUUID | empty string

Optional plan destination. The explicit productId in add controls delivery.

command.definition.readsobject[]

At most four confirmed App Store selections: connector="app_store", numeric externalId (1–20 digits), label (1–200 characters), and optional sectionIds from this plan. No duplicate apps. Copy the reviewed planner selections; do not invent app identities.

Responses

200
Success

Saved data or the requested action receipt.

400
Invalid request

Invalid identity, unsupported fields, incomplete command, or invalid plan.

403
Access required

Missing API scope or current workspace role for a write.

404
Not found

The research or run does not belong to this workspace.

409
Review required

Stale plan, incompatible run, unavailable destination, or a schedule that cannot be changed.

Example Request

POST
/external/v1/research/run
json
{
  "command": {
    "action": "start",
    "requestId": "33333333-3333-4333-8333-333333333333",
    "name": "Planning tools",
    "definition": {
      "researchMode": "baseline",
      "maxSourcesPerSection": 3,
      "sections": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "type": "market",
          "name": "Planning tools",
          "topic": "Product planning tools",
          "objective": "Understand unmet needs",
          "questions": [
            "Which needs remain unmet?"
          ]
        }
      ]
    }
  }
}

Example Response

200 OK
json
{
  "briefId": "11111111-1111-4111-8111-111111111111",
  "run": {
    "id": "44444444-4444-4444-8444-444444444444",
    "operationId": "11111111-1111-4111-8111-111111111111",
    "status": "queued",
    "sections": [],
    "nativeReadCount": 0
  }
}
POST

Manage research updates

POST /external/v1/research/updates

Choose one action in command.action. All actions require briefId. keep also requires the successfully completed addition runId and an explicit runPolicy (on_demand, daily, or weekly); it activates only the current reviewed plan after adding its findings. schedule changes an active brief using runPolicy and optional timezone. keep also accepts timezone. pause stops future automatic runs; resume restores the saved cadence; archive requires a paused brief and preserves history and Signals. Daily and weekly research consume credits when runs execute. Schedules managed by Zentrik and workspace plan limits remain enforced. These settings are separate from Brief emails. The API key’s creator must still be an active workspace owner or admin; a run scope alone cannot manage schedules.

Requirements

API scopes required:
research:manage

Request

Request body (application/json)

commandobject
Required

Exactly one keep, schedule, pause, resume, or archive command as described above. Unsupported fields are rejected.

Responses

200
Success

Saved data or the requested action receipt.

400
Invalid request

Invalid identity, unsupported fields, incomplete command, or invalid plan.

403
Access required

Missing API scope or current workspace role for a write.

404
Not found

The research or run does not belong to this workspace.

409
Review required

Stale plan, incompatible run, unavailable destination, or a schedule that cannot be changed.

Example Request

POST
/external/v1/research/updates
json
{
  "command": {
    "action": "pause",
    "briefId": "11111111-1111-4111-8111-111111111111"
  }
}

Example Response

200 OK
json
{
  "brief": {
    "id": "11111111-1111-4111-8111-111111111111",
    "configuration": {
      "state": "paused"
    }
  }
}