API Reference

This is the canonical wire contract for Configure developer and agent integrations.

Use the SDK reference when you are integrating with the TypeScript SDK. Use this page when you are writing a direct HTTP client, checking an agent-facing integration, or validating generated code against the endpoint contract.

OpenAPI: openapi.yaml

Contract Map

Surface	Use it for	Primary paths
Semantic Profile	Reading composed profile context, saving memories, and ingesting conversations or profile text.	`/v1/profile`, `/v1/profile/memories`, `/v1/profile/remember`, `/v1/profile/ingest`
Raw Profile Files	Advanced file-level CFS reads, writes, lists, search, and deletes for a user profile.	`/v1/profile/:userId/*`
Raw Agent Files	Agent-owned CFS storage and permission-gated peer reads.	`/v1/self/`, `/v1/agent/:name/`
Tools	OAuth connections, sync, live search, web fetch, and write actions.	`/v1/tools/*`

Storage And Endpoint Model

Configure stores profile data in the Configure File System (CFS), a path-addressed storage layer for identity JSON, profile documents, connected-tool state and cached artifacts, and per-agent memories.

The Memory Profile is the semantic developer-facing view composed from CFS. Most integrations should start with GET /v1/profile, POST /v1/profile/remember, POST /v1/profile/ingest, and the SDK profile.* methods rather than manipulating files directly.

Endpoint names follow the developer's intent, not the storage layer touched internally. Profile endpoints can read or write CFS because they are saving user memory. Tool endpoints can read or write CFS because they are managing connections, synced artifacts, or tool results. The lower-level /v1/profile/:userId/*, /v1/self/*, and /v1/agent/:name/* routes are raw CFS file APIs for advanced cases.

Scope

This reference covers public SDK-backed developer/runtime endpoints:

Profile and memory: /v1/profile, /v1/profile/memories, /v1/profile/remember, /v1/profile/ingest, /v1/profile/documents*
Raw user profile files: /v1/profile/:userId/*
Raw agent storage files: /v1/self/*
Raw peer agent files: /v1/agent/:name/*
Connected tools: /v1/tools/*

Dashboard, admin, hosted-surface, and migration endpoints are outside this public SDK-backed API contract unless a separate guide documents them explicitly.

Base URL

text

https://api.configure.dev

Curl examples use these placeholders:

bash

export CONFIGURE_API_KEY="sk_..."
export CONFIGURE_AGENT="your-agent"
export EXTERNAL_USER_ID="user_42"
export CONFIGURE_USER_ID="usr_..."
export CONFIGURE_TOKEN="agent_user_token_from_configure_auth"

Auth Headers

Every agent/runtime request needs an API key. User-scoped operations also need either a federated agent token or an unlinked external user ID.

Header	Required	Description
`X-API-Key`	Yes	Configure API key. Use `sk_...` on servers. `pk_...` is for browser-hosted auth and approved federated reads only.
`X-Agent`	Sometimes	Agent slug. Required when the key's developer account owns more than one active agent.
`Authorization: Bearer <token>`	Federated users	Agent-scoped token from hosted `Configure.auth()`. Must match the resolved agent.
`X-User-Id`	Unlinked users	Stable external user ID from your system. Requires a server-side `sk_...` key. Auto-creates a developer-scoped profile on first use.
`Content-Type: application/json`	Bodies	Required for POST/PUT requests with JSON bodies.

Identity Modes

Mode	Headers	Can read profile	Can write profile	Can use tools	Sharing
Federated user	`X-API-Key` + Bearer agent token	Yes	Agent namespace only	Yes, after OAuth	User-approved cross-agent reads
Unlinked user	`sk_...` + `X-User-Id`	Yes	Developer-scoped profile and agent namespace	No	Same developer only until linked

Unlinked profiles are production-supported. They are developer-scoped, metered with the unfederated read multiplier, and can be linked later by passing the same external ID to Configure.auth({ externalId }).

Federated users are component-created

The API can create or update unlinked developer-scoped profiles with sk_... plus X-User-Id. It must not create federated phone-linked users. Federated users are created or linked only through hosted Configure auth, usually <configure-auth-modal> or Configure.auth({ externalId }).

Profile Endpoints

Method	Path	Auth	Purpose
`GET`	`/v1/profile`	Federated or unlinked	Read the composed Memory Profile.
`GET`	`/v1/profile/memories`	Federated or unlinked	Query per-agent memories.
`POST`	`/v1/profile/remember`	`sk_` + federated or unlinked	Append one fact under the calling agent.
`POST`	`/v1/profile/ingest`	`sk_`; user auth depends on body mode	Extract memories from messages, text, or a batch of users.
`GET`	`/v1/profile/documents`	Federated	Read generated profile documents.
`POST`	`/v1/profile/documents/generate`	Federated	Regenerate profile documents.

GET /v1/profile

Query params:

Name	Required	Description
`user_id`	Yes	Federated Configure user ID or your external user ID.
`path`	No	Dot-path into the composed profile.
`sections`	No	Comma-separated subset: `identity`, `preferences`, `integrations`, `agents`, `summary`.
`format`	No	Use `manifest` for a lightweight shape/counts response.

Unlinked profile read. If EXTERNAL_USER_ID has not been seen before, Configure creates an unlinked developer-scoped profile.

bash

curl "https://api.configure.dev/v1/profile?user_id=${EXTERNAL_USER_ID}&sections=identity,summary,agents" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}"

Federated profile read. CONFIGURE_TOKEN must come from hosted Configure auth for this user and resolved agent.

bash

curl "https://api.configure.dev/v1/profile?user_id=${CONFIGURE_USER_ID}&sections=identity,summary,agents" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}"

GET /v1/profile/memories

Query params:

Name	Required	Description
`user_id`	Yes	Federated Configure user ID or your external user ID.
`agent`	No	Return memories for one agent.
`agents`	No	Comma-separated agent allowlist.
`from`	No	Inclusive date lower bound, `YYYY-MM-DD`.
`to`	No	Inclusive date upper bound, `YYYY-MM-DD`.

bash

curl "https://api.configure.dev/v1/profile/memories?user_id=${EXTERNAL_USER_ID}&agent=self&from=2026-04-01" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}"

POST /v1/profile/remember

Requires sk_.... Writes to /agents/{resolved-agent}/memories/{date}.md.

bash

curl -X POST "https://api.configure.dev/v1/profile/remember" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}" \
  -d '{
    "user_id": "'"${EXTERNAL_USER_ID}"'",
    "fact": "Prefers window seats on long-haul flights"
  }'

Legacy body shape { "user_id": "...", "key": "...", "value": "..." } is accepted and converted to a fact.

POST /v1/profile/ingest

Requires sk_....

Single-user mode requires either a federated Bearer token or X-User-Id:

bash

curl -X POST "https://api.configure.dev/v1/profile/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}" \
  -d '{
    "user_id": "'"${EXTERNAL_USER_ID}"'",
    "messages": [
      { "role": "user", "content": "I live in Brooklyn and prefer evening flights." },
      { "role": "assistant", "content": "Got it." }
    ],
    "sync": false
  }'

Batch mode uses only the API key and creates/updates unlinked profiles:

bash

curl -X POST "https://api.configure.dev/v1/profile/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -d '{
    "users": [
      {
        "user_id": "'"${EXTERNAL_USER_ID}"'",
        "text": "Vegetarian. Allergic to peanuts. Travels with a partner."
      }
    ],
    "sync": false
  }'

sync: false returns 202 { "status": "processing" }. sync: true waits for extraction and is best for tests or small backfills.

GET /v1/profile/documents

Returns generated profile documents for a federated user, such as user.md, preferences.md, and context.md.

bash

curl "https://api.configure.dev/v1/profile/documents?user_id=${CONFIGURE_USER_ID}" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}"

POST /v1/profile/documents/generate

Regenerates selected profile documents for a federated user.

bash

curl -X POST "https://api.configure.dev/v1/profile/documents/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{
    "user_id": "'"${CONFIGURE_USER_ID}"'",
    "documents": ["all"]
  }'

Raw Profile Files

These routes expose the profile's CFS tree directly. Use them when an integration genuinely needs file-level reads, writes, lists, or search. For normal profile context, use GET /v1/profile.

The profile CFS is the path-addressed storage behind composed profiles.

Method	Path	Auth	Purpose
`GET`	`/v1/profile/:userId`	Federated or unlinked	List a subtree.
`GET`	`/v1/profile/:userId/read`	Federated or unlinked	Read a node.
`GET`	`/v1/profile/:userId/search`	Federated or unlinked	Search nodes.
`PUT`	`/v1/profile/:userId/write`	`sk_` + federated or unlinked	Write a node.
`DELETE`	`/v1/profile/:userId`	`sk_` + federated or unlinked	Delete a node.

Read query params:

Name	Default	Description
`path`	`/`	CFS path.
`depth`	`1`	Listing depth.
`limit`	`100`, max `500`	Listing limit.

Search query params:

Name	Default	Description
`query`	Required	Search query.
`scope`	`/`	CFS subtree to search.
`limit`	`10`, max `50`	Result limit.
`files_only`	`false`	Return files only.

Examples:

List a subtree:

bash

curl "https://api.configure.dev/v1/profile/${EXTERNAL_USER_ID}?path=/&depth=2" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}"

Read a node:

bash

curl "https://api.configure.dev/v1/profile/${EXTERNAL_USER_ID}/read?path=/identity.json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}"

Write a node. For federated users, write under /agents/{resolved-agent}/.... For unlinked users, server-side integrations can also manage the developer-scoped root profile paths described below.

bash

curl -X PUT "https://api.configure.dev/v1/profile/${EXTERNAL_USER_ID}/write" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}" \
  -d '{
    "path": "/agents/your-agent/preferences.md",
    "content": "Prefers concise answers.",
    "type": "markdown",
    "mode": "overwrite"
  }'

Search nodes:

bash

curl "https://api.configure.dev/v1/profile/${EXTERNAL_USER_ID}/search?query=window%20seat&scope=/&limit=10" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "X-User-Id: ${EXTERNAL_USER_ID}"

type is json or markdown. mode is overwrite, append, or merge.

Federated users: agents can write only under /agents/{resolved-agent}/.

Unlinked users: the same developer's server-side integration can also manage root profile paths such as /identity.json, /user.md, and /documents/preferences.md.

Raw Agent Files

Method	Path	Auth	Purpose
`GET`	`/v1/self`	`sk_`	List the calling agent's own CFS.
`GET`	`/v1/self/read`	`sk_`	Read the calling agent's own CFS node.
`GET`	`/v1/self/search`	`sk_`	Search the calling agent's own CFS.
`PUT`	`/v1/self/write`	`sk_`	Write the calling agent's own CFS.
`DELETE`	`/v1/self`	`sk_`	Delete from the calling agent's own CFS.
`GET`	`/v1/agent/:name`	`sk_`	List another agent's CFS, permission-gated.
`GET`	`/v1/agent/:name/read`	`sk_`	Read another agent's CFS, permission-gated.
`GET`	`/v1/agent/:name/search`	`sk_`	Search another agent's CFS, permission-gated.

Agent identity always comes from X-API-Key plus optional X-Agent. Never construct storage paths from user input or request-body app names.

Read the calling agent's own storage:

bash

curl "https://api.configure.dev/v1/self/read?path=/memory/2026-04-29.md" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}"

Write to the calling agent's own storage:

bash

curl -X PUT "https://api.configure.dev/v1/self/write" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -d '{
    "path": "/memory/2026-04-29.md",
    "content": "Observed that short, concrete replies work best.",
    "type": "markdown",
    "mode": "append"
  }'

Read another agent's storage when permission-gated access allows it:

bash

curl "https://api.configure.dev/v1/agent/travelbot/read?path=/memory/2026-04-29.md" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}"

Tools

Tool endpoints require a federated user with an agent-scoped Bearer token. Unlinked users cannot connect or search tools until they link a phone number.

Method	Path	Purpose
`GET`	`/v1/tools`	List available tools and connection status.
`POST`	`/v1/tools/:tool/connect`	Start OAuth for `gmail`, `calendar`, `drive`, or `notion`.
`POST`	`/v1/tools/:tool/confirm`	Confirm OAuth and run initial sync.
`POST`	`/v1/tools/:tool/sync`	Sync one connected tool.
`POST`	`/v1/tools/sync`	Sync selected or all connected tools for a user.
`DELETE`	`/v1/tools/:tool`	Disconnect one tool.
`POST`	`/v1/tools/disconnect-all`	Disconnect all tools and reset profile CFS.
`POST`	`/v1/tools/gmail/messages/search`	Search Gmail.
`POST`	`/v1/tools/calendar/events/query`	Read Calendar events.
`POST`	`/v1/tools/drive/files/search`	Search Drive files.
`POST`	`/v1/tools/notion/pages/search`	Search Notion.
`POST`	`/v1/tools/web/search`	Search the web.
`POST`	`/v1/tools/web/fetch`	Fetch page content from a URL.
`POST`	`/v1/tools/calendar/events`	Create a calendar event.
`POST`	`/v1/tools/gmail/messages/send`	Send email.

Connectable tool path parameter:

text

gmail | calendar | drive | notion

Examples:

List tools:

bash

curl "https://api.configure.dev/v1/tools" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}"

Start a Gmail connection:

bash

curl -X POST "https://api.configure.dev/v1/tools/gmail/connect" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{ "callbackUrl": "https://yourapp.example.com/configure/callback" }'

Search Gmail:

bash

curl -X POST "https://api.configure.dev/v1/tools/gmail/messages/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{
    "user_id": "'"${CONFIGURE_USER_ID}"'",
    "query": "flight confirmation",
    "max_results": 10
  }'

Search the web. This requires a federated user token but does not require a connected third-party tool.

bash

curl -X POST "https://api.configure.dev/v1/tools/web/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{
    "user_id": "'"${CONFIGURE_USER_ID}"'",
    "query": "best AI calendar agents",
    "max_results": 5
  }'

Read calendar:

bash

curl -X POST "https://api.configure.dev/v1/tools/calendar/events/query" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{
    "user_id": "'"${CONFIGURE_USER_ID}"'",
    "range": "week"
  }'

Action body examples:

bash

curl -X POST "https://api.configure.dev/v1/tools/calendar/events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{
    "user_id": "'"${CONFIGURE_USER_ID}"'",
    "title": "Team sync",
    "start_time": "2026-05-01T17:00:00Z",
    "end_time": "2026-05-01T17:30:00Z",
    "description": "Weekly team sync"
  }'

bash

curl -X POST "https://api.configure.dev/v1/tools/gmail/messages/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${CONFIGURE_API_KEY}" \
  -H "X-Agent: ${CONFIGURE_AGENT}" \
  -H "Authorization: Bearer ${CONFIGURE_TOKEN}" \
  -d '{
    "user_id": "'"${CONFIGURE_USER_ID}"'",
    "to": "person@example.com",
    "subject": "Follow-up",
    "body": "Thanks for meeting today."
  }'

Setup

Use hosted Configure.auth() or <configure-auth-modal> for browser integrations and for all federated user creation/linking. Raw OTP routes, setup, dashboard, and directory endpoints are intentionally excluded from this canonical runtime reference.

Most developers should use npx configure setup or the dashboard for account, agent, and key management.

Errors

Errors return JSON with a stable code and message. Common codes:

Status	Code	Meaning
401	`api_key_missing` / `api_key_invalid`	`X-API-Key` is missing or rejected.
401	`token_missing` / `token_invalid`	Bearer token expected but absent or invalid.
403	`secret_key_required`	Endpoint or unlinked-user path requires `sk_`, not `pk_`.
403	`token_wrong_type`	User token, agent token, or developer-scope access does not match the endpoint.
403	`approval_required`	Federated user has not approved the resolved agent.
403	`access_denied`	Path is outside the resolved agent's write namespace.
402	`quota_exceeded`	Tier read or MAU cap reached.
422	`invalid_format` / `missing_field`	Request validation failed.
429	`rate_limited`	Rate limit hit.

See Errors for SDK error classes and retry guidance.

API Reference ​

Contract Map ​

Storage And Endpoint Model ​

Scope ​

Base URL ​

Auth Headers ​

Identity Modes ​

Profile Endpoints ​

GET /v1/profile ​

GET /v1/profile/memories ​

POST /v1/profile/remember ​

POST /v1/profile/ingest ​

GET /v1/profile/documents ​

POST /v1/profile/documents/generate ​

Raw Profile Files ​

Raw Agent Files ​

Tools ​

Setup ​

Errors ​

API Reference

Contract Map

Storage And Endpoint Model

Scope

Base URL

Auth Headers

Identity Modes

Profile Endpoints

GET /v1/profile

GET /v1/profile/memories

POST /v1/profile/remember

POST /v1/profile/ingest

GET /v1/profile/documents

POST /v1/profile/documents/generate

Raw Profile Files

Raw Agent Files

Tools

Setup

Errors