HTTP API Reference

The SDK is the supported integration surface for PR1. Direct HTTP is available for runtimes that cannot use the TypeScript SDK.

Authentication

Server-side calls use:

X-API-Key: sk_...
X-Agent: your-agent

API keys are issued after Launch Preview approval. Existing keys continue to work.

Linked users send the agent-scoped token returned by Configure Link:

Authorization: Bearer <configure-agent-token>

Developer-scoped users send:

X-User-Id: external-user-id

Connector and web utility routes are token-authoritative: use X-API-Key plus the agent-scoped Bearer token from Configure Link. They do not accept X-User-Id or user_id request bodies.

Sign In With Configure Routes

Sign in with Configure uses the hosted first-party page at https://accounts.configure.dev/. Your callback receives a short-lived code, never a JWT. Exchange that code on your server with a secret key.

Method	Route	Auth	Purpose
POST	/v1/auth/sign-in/return-destinations	X-API-Key: sk_...	Allowlist a web callback or native deep link for the acting agent.
GET	/v1/auth/sign-in/return-destinations	X-API-Key: sk_...	List allowlisted return destinations.
DELETE	/v1/auth/sign-in/return-destinations	X-API-Key: sk_...	Remove an allowlisted return destination.
POST	/v1/auth/sign-in/code	Authorization: Bearer <configure-agent-token>	Configure-owned hosted surface creates the return code after user approval.
POST	/v1/auth/sign-in/exchange	X-API-Key: sk_...	Exchange one code for an agent-scoped token.

POST /v1/auth/sign-in/return-destinations

{
  "return_to": "https://app.example/auth/configure/callback"
}

Return destinations must be absolute URLs or app links. https: is expected for production web callbacks. http: is accepted only for localhost development. URL fragments are stripped before storage.

POST /v1/auth/sign-in/exchange

{
  "code": "cfgsic_..."
}

Successful exchange returns the same token shape as Configure Link:

{
  "token": "eyJ...",
  "userId": "00000000-0000-0000-0000-000000000000",
  "tokenUse": "agent",
  "approved": true,
  "agent": "your-agent"
}

Codes expire after five minutes, are single-use, and are scoped to the developer account and acting agent resolved from the secret API key.

Canonical Profile Routes

Method	Route	SDK method
GET	/v1/profile	profile.read()
GET	/v1/profile/search	profile.search()
POST	/v1/profile/remember	profile.remember()
POST	/v1/profile/commit	profile.commit()

Legacy memory aliases are not mounted.

Bulk Import Routes

Bulk import is server-side only and requires a secret key. It is not a model tool, does not use profile.commit(), and does not use X-Configure-* runtime correlation headers.

Method	Route	SDK method
POST	/v1/import/profiles	configure.importProfiles()
GET	/v1/import/jobs/:jobId	configure.importJobs.get(jobId)
POST	/v1/import/jobs/:jobId/cancel	HTTP only

POST /v1/import/profiles

Headers:

X-API-Key: sk_...
X-Agent: your-agent
Content-Type: application/json

Body:

{
  "mode": "backfill",
  "idempotencyKey": "migration-2026-05-11",
  "users": [
    {
      "externalId": "customer-123",
      "profile": {
        "summary": "Longtime traveler based in SF.",
        "preferences": ["Prefers window seats."]
      },
      "conversations": [
        {
          "id": "thread-1",
          "messages": [
            { "role": "user", "content": "I usually fly out of SFO." },
            { "role": "assistant", "content": "Got it." }
          ]
        }
      ]
    }
  ]
}

Successful requests return 202 with a durable job:

{
  "id": "imp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "mode": "backfill",
  "status": "queued",
  "accepted_profiles": 1,
  "estimated_message_count": 2,
  "estimated_input_chars": 48
}

Request bodies may include externalId, conversations, profile hints, mode, and idempotency keys. Request-level idempotency is scoped to the developer account and acting agent. Bodies may not include storage paths, source, written_by, timestamps, or memory IDs. Storage namespace, source, and written_by are derived from the server-resolved agent.

Import Storage

Import writes typed memories under:

/agents/{resolved-agent}/memories/{YYYY-MM-DD}/{mem_id}.json

Import records live under:

/agents/{resolved-agent}/imports/{import_job_id}/...

Import does not write root profile files such as /identity.json, /preferences.md, /user.md, or /context.md.

Import Limits

Tier	Unique imported profiles	Max profiles/job	Max input chars/job	Concurrent import jobs
Free	100	25	2M	1
Pro	1,000	250	20M	2
Scale	10,000	1,000	200M	5
Enterprise	Unlimited	10,000 default chunk	200M direct API default; larger by staged contract	10 default; contract-managed

Global caps: 250 conversations/profile, 1,000 messages/conversation, and 20,000 characters/message.

Status	Code	Meaning
402	quota_exceeded	Unique imported-profile quota would be exceeded.
413	payload_too_large	The payload exceeds a job/input cap.
422	invalid_format	The shape is invalid or includes forbidden metadata.
429	rate_limited	Concurrent import job cap reached.

Native MCP

The native backend MCP endpoint exposes only the default profile tools in PR1:

• configure_profile_read
• configure_profile_search
• configure_profile_remember

Use the package MCP server when you need connector or action tool opt-ins.