Marcora API

Read your team's Reference Library context and Brand Foundation over plain HTTP, so tools like Clay can write copy grounded in your own sources.

The API is read-only. It doesn't enrich prospect data, generate or save content, or check claims, and it isn't a route to Marcora's MCP tools. It's available on every plan, and calls don't currently use Marcora credits.

Base URL: https://api.marcora.ai

Both endpoints return plain JSON, with Cache-Control: no-store. The API Keys page in Marcora shows the same endpoints on https://app.marcora.ai/x, and either address works.

Get a key

  1. Sign in to Marcora and open Integrations → API Keys.
  2. Give the key a name, choose how long it lasts, and select Create key.
  3. Copy the key while the panel is open. It's shown only once.

Send it on every request as Authorization: Bearer YOUR_API_KEY. Keep it private, including in screenshots and shared Clay tables.

  • Expiry. Keys expire after the period you choose, up to one year.
  • Revoking. Revoking is permanent. New requests are refused, and a read already under way can finish. A revoked key can't be turned back on, so create a new one.
  • Team and access. A key belongs to the team where you created it and uses its owner's current read access. Switching your active team doesn't change which team it reads. If the owner loses membership or read access, the key stops working. If they're added back to the same team, an unrevoked, unexpired key works again, so revoke a key when access must stay removed.
  • Where it works. Only on /v1. A key sent anywhere else is refused, and /v1 doesn't accept MCP or sign-in credentials.

Search context

POST /v1/context/search

Returns the passages from your Reference Library closest to a prompt.

curl "https://api.marcora.ai/v1/context/search" \
  -H "Authorization: Bearer $MARCORA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"prompt":"Positioning for a VP of Marketing","include_brand_foundation":true}'

{
  "relevant_context": "…ranked passages…",
  "brand_foundation": {
    "included": true,
    "elements": {
      "company_overview": "…",
      "brand_voice": "…",
      "writing_style": "…",
      "writing_examples": "…"
    },
    "link_url": "…"
  },
  "context_rag_ids": ["…passage ID…"],
  "sources": [
    {
      "context_item_id": "…",
      "context_item_name": "Positioning",
      "context_rag_ids": ["…passage ID…"],
      "link_url": "…",
      "audience": "team"
    }
  ]
}
Field Notes
prompt Required string, up to 25,000 characters. What you're looking for.
collection_ids Array of up to 5 integers. Adds these collections to the general Reference Library search. Collections you can't access are left out.
dimension_option_ids Array of up to 20 integers. Leans results toward an audience, persona or industry.
project_id UUID. Adds this project's context. A project you can't access is refused.
context_rag_ids Array of up to 100 UUIDs. Passages to exclude, for example ones you've already used.
include_brand_foundation Boolean, default false.
include_project_brief Boolean, default true.
include_only_me Boolean, default false. Adds the key owner's own Only me context, never anyone else's.

The largest request body is 65,536 bytes. Unknown fields are rejected.

The API has no list endpoints. To find collection, dimension option and project IDs, use the MCP tools list_context_collections, list_targeting_dimensions and list_projects from your Marcora MCP connection. An API key won't work there.

Reading the results. relevant_context is formatted text with ranked passages and document boundaries. sources names where each passage came from. Search returns the closest passages you're allowed to see, even when none is a good match, so check relevance yourself: a non-empty response doesn't mean a good answer was found. If there are no eligible passages, the text and arrays are empty. Private drafts and project briefs keep the same access rules as everywhere else in Marcora. An accessible project brief can appear in project_brief, and the response can include workspace_status when a workspace is empty or Brand Foundation is still being built.

Read Brand Foundation

GET /v1/brand-foundation

curl "https://api.marcora.ai/v1/brand-foundation?elements=company_overview,brand_voice" \
  -H "Authorization: Bearer $MARCORA_API_KEY"

Returns the elements you ask for, plus link_url. Leave out elements to get all four: company_overview, brand_voice, writing_style and writing_examples. An element that hasn't been set comes back as an empty string. You can list elements separated by commas or repeat the parameter. Other query parameters are rejected.

Limits

Each key can make 30 requests per minute, at least 2 seconds apart, with no bursts. The limit is shared across both endpoints.

A request over the limit gets 429 with Retry-After: 2. Wait that long before retrying. An accepted request counts toward the limit even if it then fails.

Errors

Errors are JSON with code and message.

Status Meaning
400 Invalid JSON, field or filter
401 Missing, malformed, expired, revoked or wrong type of key
403 The key's owner lacks the access this needs, or the key was used outside /v1
404 Unknown route or project
413 Request body too large
429 Over the rate limit
500 Something went wrong on our side

Error messages never repeat your prompt.

Use it in a Clay table

Clay's HTTP API enrichment is on its Growth plan and above, and included in Clay's trial.

  1. Select Add column → Add enrichment, search HTTP API and choose the one by Clay. On Configure, set Method to POST and Endpoint to https://api.marcora.ai/v1/context/search.
  2. Under Account, select Add account, name it, and add Authorization = Bearer YOUR_API_KEY. Under Headers, add Content-Type = application/json. Don't put the key under Headers: it's visible in plain text to anyone with access to the column, it takes precedence over the account, and clearing it may not stick. If you already did, delete the column and rebuild it.
  3. In Body, enter {"prompt": "…"} and type / inside the quotes to insert columns from the row. Add "include_brand_foundation": true if you want voice and style on every row.
  4. Set the pace under Custom rate limit: Request Limit 1, Duration 1000, the slowest Clay allows. Keep Retry on failure on, with Max retries 5 and Status codes to retry 429. Clay will show some rows as Queued or Retrying.
  5. In a Use AI column, set Use case to Create or modify content. In its prompt, type /, then select your HTTP column → items → relevant_context. Add to column can fail for this value with Cell data size exceeds limit (8 kB) on larger libraries.
  6. To fetch Brand Foundation on its own, add a second HTTP API column with Method GET, Endpoint https://api.marcora.ai/v1/brand-foundation and the same account. It references no other column, so Clay won't run it automatically: select Save and run, or add a run condition.
  7. A key in Headers is also copied when you duplicate a table. Share as template makes your columns, input mappings and first row of data visible to anyone, and that row can include context Marcora returned. Revoke the key when you're done testing.

What Marcora keeps

Marcora doesn't store your prompts, the context it returns, request or response bodies, or error text for /v1. No document, Clay row or credit entry is created.

Marcora keeps an operational record of each call, limited to the time, a random request ID, the method, the endpoint, the status, the duration, and the user and team. The key's own record keeps its name, team, expiry and when it was last used, which is how the rate limit works. The key itself isn't stored.

To run a search, your prompt goes to our embedding provider. Its handling of that data is governed by its own terms, and our security page lists the providers we use.

Scroll to Top