Direct HTTP API

Configure's TypeScript SDK (configure) calls a stable HTTP API. Use the SDK when your runtime supports it. Use this page when you need examples for Go, Rust, Elixir, edge runtimes, shell scripts, or another stack without an official SDK.

For the endpoint-by-endpoint contract, use the canonical API Reference or OpenAPI spec.

The HTTP API supports the same two identity modes as the SDK:

Mode	Headers	Best for	Tradeoff
Federated user	`X-API-Key` + `Authorization: Bearer <agent-token>`	User-facing apps that use `Configure.auth()`	Full user-owned identity, connected tools, and cross-agent profile sharing after user approval
Unlinked user	`sk_...` + `X-User-Id`	Backend services, batch jobs, CLIs, Slack/Discord bots, CRM imports, and apps that do not want Configure in the hot path yet	Developer-scoped profile only. Other developers' agents cannot read it until the user links a phone number later

Unlinked profiles are a production-supported API path, not just a test fixture. They let you read and update Configure profiles with your own stable user IDs before you add hosted auth or components.

Storage model

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

The Memory Profile is the semantic profile object composed from that storage. Use GET /v1/profile, POST /v1/profile/remember, and POST /v1/profile/ingest when the developer intent is "read or update this user's memory." Use raw CFS routes such as /v1/profile/:userId/read only when you need file-level access.

The endpoint noun follows the abstraction the developer is asking for. Tool APIs are under /v1/tools/* even when they persist connection state or cached artifacts in CFS.

Authentication

Every request needs an agent identity. Most profile requests also need a user identity.

Header	Value	Notes
`X-API-Key`	`sk_...`	Server-side secret key. Required for `X-User-Id` access, writes, and examples on this page.
`X-Agent`	Agent slug	Optional unless the key's developer account has more than one agent. The API key plus this header resolves `req.agent`.
`Authorization: Bearer <jwt>`	Agent-scoped token from `configure:authenticated`	Federated user path. The token must belong to the same agent resolved from the API key.
`X-User-Id`	Stable user ID from your system	Unlinked user path. Requires `sk_...`, is scoped to your developer account, and is auto-created on first use.

Keep secret keys server-side

Never embed sk_ keys in browser code, mobile bundles, or any client surface. Browser integrations should use pk_ keys with hosted Configure surfaces. X-User-Id unlinked profile access is a server-side API path and requires sk_.

Agent identity comes from the key

The acting agent is resolved from X-API-Key and optional X-Agent. Do not rely on request-body app names or caller-supplied paths for agent identity. User profile writes are rejected unless the path is allowed for the resolved agent.

Read and update an unlinked profile

Use your own stable ID in both user_id and X-User-Id. On first contact Configure creates a developer-scoped internal profile for that external ID.

bash

curl "https://api.configure.dev/v1/profile?user_id=user_42" \
  -H "X-API-Key: sk_..." \
  -H "X-User-Id: user_42"

Save a memory under the calling agent's namespace:

bash

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

Write structured profile data for an unlinked user:

bash

curl -X PUT https://api.configure.dev/v1/profile/user_42/write \
  -H "X-API-Key: sk_..." \
  -H "X-User-Id: user_42" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/identity.json",
    "content": "{\"name\":{\"value\":\"Sarah Chen\",\"source\":\"crm\"},\"occupation\":{\"value\":\"Product Manager\",\"source\":\"crm\"}}",
    "type": "json",
    "mode": "merge"
  }'

For unlinked users only, developer-scoped writes may manage root profile paths like /identity.json, /user.md, and /documents/preferences.md. For federated users, agents can write only inside their own namespace: /agents/{resolved-agent}/....

Read a federated profile

Federated users come from the hosted auth flow. The frontend receives token and userId from configure:authenticated; your backend sends the token as a Bearer token.

bash

curl "https://api.configure.dev/v1/profile?user_id=usr_abc123" \
  -H "X-API-Key: sk_..." \
  -H "Authorization: Bearer <agent-scoped-token>"

The user_id query param must match the user resolved from the token. The SDK fills this in for you.

Raw file operations

These routes expose the Configure File System directly. They are useful for explicit file reads, writes, lists, and search. Most agent context should come from the semantic Memory Profile first.

Read a node

bash

curl "https://api.configure.dev/v1/profile/user_42/read?path=/identity.json" \
  -H "X-API-Key: sk_..." \
  -H "X-User-Id: user_42"

Returns { path, content, type, mode } or null if the node does not exist or the agent cannot read it.

List a subtree

bash

curl "https://api.configure.dev/v1/profile/user_42?path=/&depth=2" \
  -H "X-API-Key: sk_..." \
  -H "X-User-Id: user_42"

Returns { entries, count }. Default path is /, default depth is 1, max limit is 500.

Write a node

bash

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

type is "json" or "markdown". mode is "overwrite", "append", or "merge" (shallow JSON merge).

Delete a node

bash

curl -X DELETE "https://api.configure.dev/v1/profile/user_42?path=/agents/your-agent/notes/old.md" \
  -H "X-API-Key: sk_..." \
  -H "X-User-Id: user_42"

The same write rules apply to deletes.

Ingest and batch seed

Single-user ingest works for either federated users or unlinked users.

bash

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

Batch mode creates or updates many unlinked profiles in one call and does not need a per-user token.

bash

curl -X POST https://api.configure.dev/v1/profile/ingest \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "user_id": "user_42",
        "conversations": [
          { "messages": [
            { "role": "user", "content": "I live in Brooklyn and prefer evening flights" },
            { "role": "assistant", "content": "Got it." }
          ]}
        ]
      },
      {
        "user_id": "user_43",
        "text": "Vegetarian. Allergic to peanuts. Travels with a partner."
      }
    ],
    "sync": false
  }'

sync: false returns 202 { status: "processing" } immediately. sync: true blocks until extraction completes; use it for tests and small backfills.

What unlinked users can and cannot do

When you call with X-User-Id and no Bearer token, Configure:

Looks up (developer_account, external_id) in external_user_mappings.
Auto-creates the mapping if it does not exist.
Resolves it to an internal UUID for storage.
Auto-approves the calling agent for that developer-scoped profile.
Reads and writes against that developer-scoped profile.

Unlinked profiles can:

be read with GET /v1/profile
be updated with POST /v1/profile/remember, POST /v1/profile/ingest, and CFS writes
be batch-seeded from historical conversations or CRM data
be linked to a phone number later with Configure.auth({ externalId })

Unlinked profiles cannot:

be read by other developers' agents
participate in cross-developer or cross-agent federated profile sharing
connect Gmail, Calendar, Drive, or Notion until the user completes hosted OAuth from a federated session
use tool search/action endpoints that require an agent-scoped Bearer token

Unlinked-user reads are metered at the configured premium multiplier.

Link later

To turn an unlinked profile into a federated profile, mount hosted auth and pass the same external ID:

html

<div id="auth"></div>
<script src="https://configure.dev/js/configure.js"></script>
<script>
  Configure.auth({
    el: "#auth",
    publishableKey: "pk_...",
    agent: "your-agent",
    externalId: "user_42",
    theme: "light"
  });
</script>

After phone verification, Configure merges the developer-scoped profile into the phone-linked user profile. From that point forward, the user can approve other agents and connected tools normally.

Endpoint summary

Method	Path	Auth	Purpose
GET	`/v1/profile`	`sk_`/`pk_` + Bearer, or `sk_` + `X-User-Id`	Read composed profile
GET	`/v1/profile/memories`	`sk_`/`pk_` + Bearer, or `sk_` + `X-User-Id`	Query memories
POST	`/v1/profile/remember`	`sk_` + Bearer or `X-User-Id`	Save one fact under the calling agent
POST	`/v1/profile/ingest`	`sk_` + Bearer or `X-User-Id` for single-user; `sk_` only for batch	Extract memories from messages or text
GET	`/v1/profile/:userId`	`sk_`/`pk_` + Bearer, or `sk_` + `X-User-Id`	List profile CFS subtree
GET	`/v1/profile/:userId/read`	`sk_`/`pk_` + Bearer, or `sk_` + `X-User-Id`	Read profile CFS node
GET	`/v1/profile/:userId/search`	`sk_`/`pk_` + Bearer, or `sk_` + `X-User-Id`	Search profile CFS
PUT	`/v1/profile/:userId/write`	`sk_` + Bearer or `X-User-Id`	Write profile CFS node
DELETE	`/v1/profile/:userId`	`sk_` + Bearer or `X-User-Id`	Delete profile CFS node

Tool connection, tool search, and tool action endpoints require a federated user token. Use hosted auth first, then call the tools APIs with the agent-scoped Bearer token.

Errors

All errors return JSON with a stable code and human-readable message. The HTTP status reflects the category.

Status	Code	Meaning
401	`api_key_missing` / `api_key_invalid`	`X-API-Key` missing or rejected
401	`token_missing` / `token_invalid`	Bearer JWT expected but absent or malformed
403	`secret_key_required`	Endpoint needs `sk_`, you sent `pk_`
403	`token_wrong_type`	Wrong token authority for the endpoint
403	`access_denied`	Path is outside the resolved agent's writable namespace
403	`approval_required`	Federated user has not approved this agent
422	`invalid_format` / `missing_field`	Validation failed
429	`rate_limited`	Per-developer rate limit hit
402	`quota_exceeded`	Tier read or MAU cap reached

See the Errors reference for the full list and SDK error classes.

When to switch to the SDK

If your runtime supports Node, install configure instead of hand-writing an HTTP client. The SDK:

Resolves X-API-Key, X-Agent, and X-User-Id from one client config
Composes profiles into a system-prompt-ready string via profile.format({ guidelines: true })
Exposes CONFIGURE_TOOLS for model tool loops
Maps errors to typed exceptions
Keeps Configure File System path conventions consistent

The HTTP surface above is the same one the SDK calls.

Direct HTTP API ​

Storage model ​

Authentication ​

Read and update an unlinked profile ​

Read a federated profile ​

Raw file operations ​

Read a node ​

List a subtree ​

Write a node ​

Delete a node ​

Ingest and batch seed ​

What unlinked users can and cannot do ​

Link later ​

Endpoint summary ​

Errors ​

When to switch to the SDK ​

Direct HTTP API

Storage model

Authentication

Read and update an unlinked profile

Read a federated profile

Raw file operations

Read a node

List a subtree

Write a node

Delete a node

Ingest and batch seed

What unlinked users can and cannot do

Link later

Endpoint summary

Errors

When to switch to the SDK