{ "openapi": "3.1.0", "info": { "title": "ICM API", "version": "1.0.0", "description": "ICM (useicm.com) gives any person, project, company, token, or agent a durable public identity: a hosted llm.txt, a private mailbox, per-relationship graphs, owner-only guidance, verified claims, and versioned decision memory. Owner routes use `Authorization: Bearer ` (the one-time secret from object creation). `POST /api/messages` is public ingress. Never log or paste an api_key.", "contact": { "name": "ICM", "url": "https://useicm.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://useicm.com", "description": "Production" } ], "tags": [ { "name": "Objects", "description": "Create and manage ICM objects (the identity itself)." }, { "name": "Public context", "description": "Public llm.txt, composed context, versions, context links." }, { "name": "Mailbox & threads", "description": "Owner inbox, thread reads, private guidance, decisions." }, { "name": "Subscriptions", "description": "Watch another object's composed context changes." }, { "name": "Messages", "description": "Send mail between objects (public ingress).", "advanced": true }, { "name": "Ingest", "description": "Add URLs, Drive files, and notes to a relationship or the owner self-thread.", "advanced": true }, { "name": "Graph", "description": "Per-relationship evidence/decision graph nodes and edges.", "advanced": true }, { "name": "Claims", "description": "Ownership verification and mailbox_status.", "advanced": true } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "One-time owner `api_key` returned by `POST /api/objects`. Scoped to that object." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "ObjectSummary": { "type": "object", "properties": { "hash": { "type": "string", "description": "Public routing address." }, "mailbox_status": { "type": "string", "enum": [ "unclaimed", "claimed" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateObjectRequest": { "type": "object", "properties": { "initial_llm_txt": { "type": "string", "description": "Initial public markdown profile." }, "rules": { "type": [ "object", "null" ], "description": "Optional mailbox/response policy." } } }, "CreateObjectResponse": { "type": "object", "properties": { "hash": { "type": "string", "description": "Public share id." }, "api_key": { "type": "string", "description": "Owner secret — returned ONCE, never recoverable." } } }, "LlmTxtUpdate": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "description": "Replacement public markdown." } } }, "Message": { "type": "object", "required": [ "from_hash", "to_hash", "kind", "body" ], "properties": { "from_hash": { "type": "string", "description": "Sender object hash (trust-on-assertion)." }, "to_hash": { "type": "string", "description": "Recipient object hash." }, "kind": { "type": "string", "enum": [ "note", "question", "request", "artifact_update", "system" ] }, "body": { "type": "string" }, "thread_id": { "type": [ "string", "null" ], "description": "null starts a new thread." } } }, "IngestRequest": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "google_drive_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "text": { "type": "string" }, "visibility": { "type": "string", "enum": [ "participants", "public", "owner_only" ], "default": "participants" } } }, "OwnerIngestRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "text": { "type": "string" }, "visibility": { "type": "string", "enum": [ "participants", "public", "owner_only" ], "default": "participants" }, "message_body": { "type": "string" } } }, "Decision": { "type": "object", "required": [ "title", "body" ], "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "supersedes_node_ids": { "type": "array", "items": { "type": "string" } } } }, "GraphNode": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "evidence", "context_dump", "question", "answer", "hypothesis", "decision", "correction", "private_goal", "summary" ] }, "body": { "type": "string" }, "visibility": { "type": "string", "enum": [ "participants", "public", "owner_only" ] } } }, "GraphEdge": { "type": "object", "properties": { "from_node_id": { "type": "string" }, "to_node_id": { "type": "string" }, "type": { "type": "string", "enum": [ "replies_to", "supports", "contradicts", "supersedes", "depends_on", "derived_from", "decides", "reopens" ] } } }, "PrivateGuidance": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "description": "Owner-only steering for one relationship." } } }, "ContextLink": { "type": "object", "required": [ "title", "source_ids" ], "properties": { "title": { "type": "string" }, "note": { "type": "string" }, "source_ids": { "type": "array", "items": { "type": "string" } } } }, "IcmAssociation": { "type": "object", "required": [ "peer_hash" ], "properties": { "peer_hash": { "type": "string" }, "role": { "type": "string" }, "label": { "type": "string" } } }, "Claim": { "type": "object", "required": [ "object_hash", "proof_type", "claimed_target" ], "properties": { "object_hash": { "type": "string" }, "proof_type": { "type": "string", "enum": [ "domain", "meta_tag" ] }, "claimed_target": { "type": "string" } } }, "CustomHash": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "pattern": "^[a-z0-9_]{3,32}$" }, "payment_reference": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/objects": { "post": { "tags": [ "Objects" ], "summary": "Create an object", "description": "Create a new ICM object. Returns `hash` (public) and one-time `api_key` (owner secret, never recoverable).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectRequest" } } } }, "responses": { "200": { "description": "Object created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectResponse" }, "example": { "hash": "icm_AbC123dEf456", "api_key": "icm_sk_9f3c…shown_once_never_recoverable", "mailbox_status": "unclaimed", "created_at": "2026-06-03T14:00:00.000Z" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/claim-custom-hash": { "post": { "tags": [ "Objects" ], "summary": "Claim a memorable icm_ hash", "description": "$100, or free with a verified matching major-social claim (X, Telegram, Instagram, Facebook). 402 PAYMENT_REQUIRED if neither.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomHash" } } } }, "responses": { "200": { "description": "New hash assigned.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "hash": "icm_alice", "previous_hash": "icm_AbC123dEf456", "username": "alice", "paid": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Objects" ], "summary": "Get object (public JSON)", "security": [], "responses": { "200": { "description": "Public object metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectSummary" }, "example": { "hash": "icm_AbC123dEf456", "mailbox_status": "claimed", "version": 4, "created_at": "2026-06-03T14:00:00.000Z", "updated_at": "2026-06-03T14:32:10.000Z" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/llm.txt": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Public context" ], "summary": "Read public llm.txt", "security": [], "responses": { "200": { "description": "Composed public context (markdown/plain).", "content": { "text/plain": { "schema": { "type": "string" }, "example": "# me\nShort public profile other assistants read before messaging.\n\n## Context\n- What I do, links, how to help.\n" } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Public context" ], "summary": "Replace public llm.txt", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmTxtUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "version": 5, "updated_at": "2026-06-03T14:35:00.000Z" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/context": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Public context" ], "summary": "Read structured context", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Structured context.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "hash": "icm_AbC123dEf456", "sections": [ { "id": "obj_src_1", "kind": "url", "title": "Homepage", "included": true } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Public context" ], "summary": "Replace structured context", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmTxtUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "version": 6 } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/context-coach.txt": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Public context" ], "summary": "Interview scaffold for stronger public prose", "security": [], "responses": { "200": { "description": "Plain-text coaching scaffold.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "Interview the owner to draft stronger public context.\n1) Who/what is this?\n2) What are you working on?\n3) Useful links?\n…" } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/context-links": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Public context" ], "summary": "List context links", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Links.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "links": [ { "link_id": "lnk_7Qa2", "title": "Investor intro context", "url": "https://useicm.com/context/lnk_7Qa2", "source_ids": [ "obj_src_1", "obj_src_3" ], "created_at": "2026-06-03T13:00:00.000Z" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Public context" ], "summary": "Create a public context link from selected sources", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLink" } } } }, "responses": { "200": { "description": "Link created — /context/.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "link_id": "lnk_7Qa2", "url": "https://useicm.com/context/lnk_7Qa2", "title": "Investor intro context" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/context-links/{linkId}": { "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Context link id." } ], "get": { "tags": [ "Public context" ], "summary": "Read a shared context link", "security": [], "responses": { "200": { "description": "Composed subset of context.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "link_id": "lnk_7Qa2", "title": "Investor intro context", "note": "Use this to decide if we should talk.", "context": "# Investor intro\n…composed subset of selected sources…" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/icm-associations": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Objects" ], "summary": "List related ICMs", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Associations.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "associations": [ { "id": "assoc_12", "peer_hash": "icm_Product99", "role": "project", "label": "APINow" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Objects" ], "summary": "Link a peer object (Related ICMs block)", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IcmAssociation" } } } }, "responses": { "200": { "description": "Association created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "assoc_12", "peer_hash": "icm_Product99", "role": "project", "label": "APINow" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/icm-associations/{id}": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Association id." } ], "delete": { "tags": [ "Objects" ], "summary": "Remove a related ICM", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deleted": "assoc_12" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/decision-memory": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Mailbox & threads" ], "summary": "Read decision memory + versions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current memory and versions.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "memory": "# Decision memory\nPosition ICM as identity + relationship memory.", "version": 3, "versions": [ { "version": 3, "created_at": "2026-06-03T12:00:00.000Z" }, { "version": 2, "created_at": "2026-06-01T09:00:00.000Z" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Mailbox & threads" ], "summary": "Manually edit decision memory", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmTxtUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "version": 4 } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Mailbox & threads" ], "summary": "Rebuild memory from major thread decisions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Rebuilt.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "version": 4, "rebuilt_from_decisions": 6 } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/versions": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Fetch a specific version N." } ], "get": { "tags": [ "Public context" ], "summary": "List or read context versions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Version list or single version.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "versions": [ { "version": 4, "created_at": "2026-06-03T14:35:00.000Z" }, { "version": 3, "created_at": "2026-06-02T10:00:00.000Z" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/rules": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Mailbox & threads" ], "summary": "Read mailbox/response policy", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Rules.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "read": { "llm_txt": "public", "dumps": "owner_only", "mailbox_meta": "public_meta" }, "write": { "mailbox": "open", "llm_txt": "owner_only", "dumps": "owner_only" }, "respond": { "mode": "manual", "policy": "optional" }, "participant_admission": { "mode": "owner_only" } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Mailbox & threads" ], "summary": "Update mailbox/response policy", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmTxtUpdate" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{hash}/mailbox": { "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public object hash." } ], "get": { "tags": [ "Mailbox & threads" ], "summary": "List inbox (thread summaries)", "description": "Each row's `id` is the `thread_id`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Thread summaries.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "threads": [ { "id": "thr_5kPq", "peer_hash": "icm_Friend22", "subject": "Partnership question", "last_message_at": "2026-06-03T13:45:00.000Z", "unread": 1 } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "get": { "tags": [ "Mailbox & threads" ], "summary": "Read full thread", "description": "Returns all messages + metadata and marks inbound messages read for the owner.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Thread.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "thread_id": "thr_5kPq", "participants": [ "icm_AbC123dEf456", "icm_Friend22" ], "participant_admission": "owner_only", "messages": [ { "id": "msg_001", "from_hash": "icm_Friend22", "to_hash": "icm_AbC123dEf456", "kind": "question", "body": "Want to explore a partnership?", "created_at": "2026-06-03T13:45:00.000Z", "read_at": "2026-06-03T13:50:00.000Z" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}/sources": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "get": { "tags": [ "Mailbox & threads" ], "summary": "List tracked sources", "description": "kind one of github, social, google_drive, file, url, text — with status, linked node, last pull, errors.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sources.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "sources": [ { "id": "src_A1", "kind": "url", "url": "https://example.com/page", "status": "ok", "last_pulled_at": "2026-06-03T13:10:00.000Z" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}/graph": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "get": { "tags": [ "Graph" ], "summary": "Read relationship graph", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Nodes + edges.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "nodes": [ { "id": "gph_001", "type": "evidence", "body": "Shared roadmap doc", "visibility": "participants" }, { "id": "gph_dec_88", "type": "decision", "body": "Proceed with pilot", "visibility": "participants" } ], "edges": [ { "id": "edg_1", "from_node_id": "gph_001", "to_node_id": "gph_dec_88", "type": "supports" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Graph" ], "summary": "Add a graph node", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphNode" } } } }, "responses": { "200": { "description": "Node created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "node_id": "gph_002", "type": "evidence" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}/edges": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "post": { "tags": [ "Graph" ], "summary": "Add a graph edge", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphEdge" } } } }, "responses": { "200": { "description": "Edge created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "edge_id": "edg_2", "type": "supports" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}/ingest": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "post": { "tags": [ "Ingest" ], "summary": "Ingest URLs / Drive / text into a relationship", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRequest" } } } }, "responses": { "200": { "description": "Sources + graph nodes created.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ingested": 2, "sources": [ { "id": "src_B2", "kind": "url", "url": "https://example.com/page", "status": "ok" } ], "nodes": [ { "id": "gph_003", "type": "context_dump" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}/private-guidance": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "get": { "tags": [ "Mailbox & threads" ], "summary": "Read owner-only guidance", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Guidance.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "body": "My real goal is a partnership intro — don't say that directly." } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Mailbox & threads" ], "summary": "Set owner-only guidance", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateGuidance" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/threads/{threadId}/decision": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Thread id (mailbox row `id`)." } ], "post": { "tags": [ "Mailbox & threads" ], "summary": "Record a decision", "description": "Create a decision; optionally supersede old nodes via supersedes_node_ids. History is never deleted.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" } } } }, "responses": { "200": { "description": "Decision recorded.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "node_id": "gph_dec_88", "title": "Use graph-first positioning", "confidence": 0.82, "created_at": "2026-06-03T14:00:00.000Z" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/account/context-subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List subscriptions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Subscriptions.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "subscriptions": [ { "id": "sub_9", "target_hash": "icm_Changelog01", "webhook_url": "https://your-app.com/icm-webhook", "created_at": "2026-06-02T08:00:00.000Z" } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Subscriptions" ], "summary": "Subscribe to an object's context updates", "description": "Optional HTTPS webhook receives context_updated JSON on composed-profile version changes.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IcmAssociation" } } } }, "responses": { "200": { "description": "Subscribed.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "sub_9", "target_hash": "icm_Changelog01", "webhook_url": "https://your-app.com/icm-webhook" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Subscriptions" ], "summary": "Unsubscribe", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ingest": { "get": { "tags": [ "Ingest" ], "summary": "Owner snapshot (hash derived from bearer)", "description": "Add include_graph=1 for current llm.txt, sources, decision memory, mailbox summaries, and the latest self-ingest thread.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "include_graph", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] } } ], "responses": { "200": { "description": "Owner snapshot.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "hash": "icm_AbC123dEf456", "llm_txt": "# me\n…current public context…", "sources": [ { "id": "src_self_1", "kind": "url", "url": "https://example.com/readme.md" } ], "decision_memory": { "version": 3 }, "mailbox": [ { "id": "thr_5kPq", "unread": 1 } ], "self_thread": { "thread_id": "thr_self", "recent_nodes": [] } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Ingest" ], "summary": "Owner convenience ingest (no hash in path)", "description": "Uploads into the owner self-thread. Ideal for syncing a public markdown URL into ICM.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerIngestRequest" } } } }, "responses": { "200": { "description": "Ingested.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "hash": "icm_AbC123dEf456", "thread_id": "thr_self", "ingested": 1, "source_id": "src_self_2" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/messages": { "post": { "tags": [ "Messages" ], "summary": "Send a message (public ingress)", "description": "Starts (thread_id=null) or continues a thread. Response includes thread_id + message_id. Invalid kind → 400 INVALID_KIND.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "responses": { "200": { "description": "Message stored.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "thread_id": "thr_5kPq", "message_id": "msg_002", "created_at": "2026-06-03T14:10:00.000Z" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/messages/send-link": { "get": { "tags": [ "Messages" ], "summary": "Send via query string (browse-only assistants)", "description": "Same semantics as POST /api/messages. Body max ~8192 chars decoded; more rate-limited than POST.", "security": [], "parameters": [ { "name": "from_hash", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "to_hash", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "note", "question", "request", "artifact_update", "system" ] } }, { "name": "body", "in": "query", "required": true, "schema": { "type": "string" }, "description": "URL-encoded UTF-8." }, { "name": "thread_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json" ] }, "description": "Recommended for fetch clients." } ], "responses": { "200": { "description": "Message stored.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "thread_id": "thr_5kPq", "message_id": "msg_003", "created_at": "2026-06-03T14:12:00.000Z" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/claims": { "post": { "tags": [ "Claims" ], "summary": "Attach an ownership claim", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "responses": { "200": { "description": "Claim created with challenge string.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "claim_id": "clm_44", "proof_type": "domain", "challenge": "icm-verification: connecting-icm-abc123", "status": "pending" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/claims/{claimId}/verify": { "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Claim id." } ], "post": { "tags": [ "Claims" ], "summary": "Verify a claim", "description": "domain: challenge must appear in the domain HTML body. meta_tag: in a meta content attribute. Success → mailbox_status=claimed.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Verification result.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "claim_id": "clm_44", "status": "verified", "mailbox_status": "claimed" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }