HTTP API
Base URL: https://api.meshpoint.dev. JSON in and out. Every /v1 route except the sign-in routes takes:
Authorization: Bearer <token>The token is the one meshpoint login stores: base64url(claims).base64url(signature), Ed25519-signed by your organization’s key, with claims {org, user, agent, exp}. It lives 7 days; refresh it with the session’s refresh secret. Programs that need a token without a browser use the device-code flow below. There are no cookies and no API keys.
Project ids are host--owner--repo, derived from the repository’s origin clone URL (the SDK’s projectIdFromRemote does this). Branch is the git branch name.
Memory
Section titled “Memory”| Route | Body or query | Notes |
|---|---|---|
GET /v1/recall |
project, branch, budget (tokens, default 3000), fresh=1 |
The branch’s ranked items within the budget, plus the last checkpoint. Served from the edge and up to 60 s stale; fresh=1 reads the origin. Response header x-meshpoint-source: kv or do. |
GET /v1/presence |
project, branch |
Agents live on the branch in the last 5 minutes, with the paths they touched. |
POST /v1/capture |
{project, branch, turns: [{body, paths?, at?}], checkpoint?} |
Stores raw turns. Answers 202 at the edge; the write completes after the response. Mask credentials before sending; the platform does not. |
POST /v1/presence |
{project, branch, paths} |
Presence without a turn. |
POST /v1/items |
{project, branch, items: [{id, kind, title, body, created_at?, confirmations?, provenance?}]} |
Writes items and records a checkpoint. Provenance defaults to {agent, user} from the token. Answers {count}. |
POST /v1/retract |
{project, id} |
Soft-deletes an item. 202, or 404 when the id is unknown. |
POST /v1/fork |
{project, target, mode: "items" | "full"} |
Copies a project’s memory into a new project id. |
GET /v1/items |
project, branch, retracted=1, limit |
Items newest first; retracted ones only when asked. |
GET /v1/project |
project |
Branches with item counts and checkpoint times, presence per branch, captures in the last hour. |
GET /v1/activity |
project, limit |
Recent events derived from stored data. |
GET /v1/stats |
project |
Row counts. |
Item kinds: decision, gotcha, convention, fact, status, todo.
Sign-in and tokens
Section titled “Sign-in and tokens”| Route | Auth | Notes |
|---|---|---|
GET /v1/auth/start?nonce&agent[&org][&provider] + port or return_to |
none | Starts a browser sign-in. provider is authkit (default), GoogleOAuth, MicrosoftOAuth or GitHubOAuth. The CLI passes port and listens on 127.0.0.1:<port>; the console passes return_to. |
POST /v1/auth/exchange {code, nonce} |
none | Trades the one-time grant (2 minutes) for {token, exp, refresh, org, org_name, user, email, agent}. nonce is the value the client started with; a mismatch burns the grant. Optional until 1.0. |
POST /v1/auth/refresh {refresh} |
none | A new 7-day token for a live session whose user is still a member. |
POST /v1/auth/switch {refresh, org} |
none | Moves a live session to another organization the user belongs to. Returns a new grant; the old refresh secret stops working. |
POST /v1/auth/logout {refresh} |
none | Revokes the session. |
POST /v1/auth/device {agent, hostname?} |
none | Device-code sign-in. 201 {device_code, user_code, verification_uri, verification_uri_complete, expires_in: 900, interval: 5}. |
GET /v1/auth/device?user_code |
member | What the console shows before approving: {agent, hostname, created_at, expires_at, status}. |
POST /v1/auth/device/approve {user_code, decision} |
member | approve binds the code to the caller’s user and organization; deny ends it. |
POST /v1/auth/device/token {device_code} |
none | Poll every interval seconds. 200 with the exchange grant once approved; 428 authorization_pending; 403 access_denied; 410 when expired. |
GET /v1/me |
token | User, current organization and role, all organizations with their member counts. |
PATCH /v1/me {name} |
token | Sets the display name. It stays across sign-ins; an empty name takes the provider’s name again at the next sign-in. |
DELETE /v1/me/orgs/:org |
token | Leaves that organization and ends the caller’s agent sessions there. 400 for the last owner or the only member. |
DELETE /v1/me {confirm} |
token | confirm must equal DELETE. Refused while the caller is the only owner of an organization with other members. Deletes organizations where the caller is the only member, then the account. Answers {deleted, orgs_deleted, orgs_left}. |
GET /v1/me/onboarding |
token | First-run milestones: {cli_signed_in_at, first_session_at, first_items_at, first_project}. |
Device-code flow for an agent
Section titled “Device-code flow for an agent”POST /v1/auth/devicewith your agent name. Show the userverification_uri_completeanduser_code.- Poll
POST /v1/auth/device/tokeneveryintervalseconds. Back off on 429. - On 200, store the grant:
tokenfor requests,refreshforPOST /v1/auth/refreshwhenexpis near.
Never ask the user to paste a token into a conversation.
Organization
Section titled “Organization”Auth column: member is any member, admin is admin or owner, owner is owner only. Roles are explained in Teams and organizations.
| Route | Auth | Notes |
|---|---|---|
GET /v1/org |
member | Organization, members, key ids and plan (plan, seats and seats used, projects used and limit, retention days, subscription status). |
GET | POST /v1/org/invites {email, role?} |
admin | role is member (default), admin or owner; only owners may send the last two. Accepted at the invitee’s next sign-in with that email. POST answers {id, email, role, emailed}. |
DELETE /v1/org/invites/:id |
admin | Revokes a pending invite and frees its seat. Admins revoke member invites; owners revoke any. |
DELETE /v1/org/members/:user |
admin | Removes a member and revokes their sessions. Admins remove members; owners remove anyone but themselves. |
PATCH /v1/org/members/:user {role} |
owner | Sets member, admin or owner. The last owner cannot be demoted. |
GET /v1/org/sessions, POST /v1/org/sessions/revoke {id} |
member (own), admin (all) | Logged-in agents. |
POST /v1/org/keys/rotate {revoke_sessions?} |
admin | Retires the active signing keys. Old tokens die within about 2 minutes. |
GET /v1/org/projects |
member | Projects recorded on their first write. |
GET /v1/org/export |
admin | One JSON document: organization, members, pending invites, projects with every item (retracted flagged) and checkpoints. Raw turns are not included. Sent as an attachment. |
POST /v1/org/billing/checkout {seats, return_url} |
owner | Stripe Checkout URL for the Team subscription. |
POST /v1/org/billing/portal {return_url} |
owner | Stripe customer portal URL. |
PATCH /v1/org {name} |
owner | Renames the organization, 1 to 64 characters. The Stripe customer name follows when billing exists. |
DELETE /v1/org {confirm} |
owner | confirm must equal the organization’s name. Cancels billing, purges every project, removes the organization and the accounts of members with no other organization. Answers {deleted, projects, members, users_removed, billing_cancelled}. |
Errors and limits
Section titled “Errors and limits”Errors are {"error": "<message>"} with the HTTP status. 401 for a missing or invalid token, or for a token whose membership in the organization has ended (sign in again), 403 for a role the route does not allow or a suspended organization, 402 when a plan limit blocks growth (see Plans), 404 for an unknown project or item, 409 for a device code that is no longer pending, 413 for a body over 2 MB, 429 with a Retry-After header when an abuse ceiling is reached (public auth routes per client address, every authenticated route per organization; far above normal use, never a plan limit), 502 when a billing provider call fails.
Per request: at most 200 turns of 256 KB each, 200 items with a 300-character title and a 32 KB body, 200 presence paths of 512 characters, a 32 KB checkpoint. A recall for a project the organization never wrote answers empty with x-meshpoint-source: none.
Bulk clients should send one POST /v1/capture per minute per session, as the CLI does, rather than one per turn.
Discovery
Section titled “Discovery”An A2A agent card at meshpoint.dev/.well-known/agent.json describes this API for agents, and meshpoint.dev/llms.txt is the plain-text index. See SDK and agents.
