{"openapi":"3.0.3","info":{"title":"SLEDS API","description":"Shared context layer for AI-powered work. Connect your AI tools to a shared sled — every session shares the same memory, decisions, specs, artifacts, and history.","version":"1.0.0","contact":{"name":"SLEDS","url":"https://sleds.ai"}},"servers":[{"url":"https://api.sleds.ai","description":"SLEDS API (Production)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"SLEDS API key (e.g. sleds_ak_...)"}},"schemas":{"Thread":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"spaceId":{"type":"string","format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"title":{"type":"string"},"tool":{"type":"string","enum":["claude","cursor","chatgpt","ai-studio","figma","slack","web","api","mcp"]},"externalRef":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","paused","completed","archived"]},"tags":{"type":"array","items":{"type":"string"}},"lastActivityAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ThreadUpdate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"threadId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["observation","summary_refresh","decision","question","status_change","asset_produced"]},"content":{"type":"string"},"structured":{"type":"object","nullable":true},"observedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Asset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"spaceId":{"type":"string","format":"uuid"},"threadId":{"type":"string","format":"uuid","nullable":true},"createdById":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","enum":["spec","document","code","image","design","config","reference","note"]},"content":{"type":"string","nullable":true},"fileUrl":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"version":{"type":"integer"},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SearchResult":{"type":"object","properties":{"entityType":{"type":"string","enum":["thread","asset"]},"entity":{"type":"object"},"score":{"type":"number"},"matchType":{"type":"string","enum":["semantic","fulltext","hybrid"]}}},"Space":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"role":{"type":"string"}}},"StreamEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"actorId":{"type":"string","nullable":true},"actorName":{"type":"string","nullable":true},"actorTool":{"type":"string","nullable":true},"targetId":{"type":"string","nullable":true},"targetType":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}},"parameters":{"slug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Sled slug (URL-safe identifier)"},"threadId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Thread ID"},"assetId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Asset ID"}}},"paths":{"/api/spaces":{"get":{"operationId":"listSpaces","summary":"List your sleds","description":"Returns all sleds the authenticated user has access to.","tags":["Spaces"],"responses":{"200":{"description":"List of sleds","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Space"}}}}}}}}},"post":{"operationId":"createSpace","summary":"Create a new sled","tags":["Spaces"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string","description":"Display name"},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$","description":"URL identifier"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/api/spaces/{slug}":{"get":{"operationId":"getSpace","summary":"Get sled details","tags":["Spaces"],"parameters":[{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Sled details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Space"}}}}}},"404":{"description":"Not found"}}}},"/api/spaces/{slug}/threads":{"get":{"operationId":"listThreads","summary":"List threads in a sled","description":"Returns threads with optional filtering by status, tool, tags.","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/slug"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","paused","completed","archived"]}},{"name":"tool","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated tags"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Thread list with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Thread"}},"meta":{"type":"object"}}}}}}}},"post":{"operationId":"createThread","summary":"Create a thread","description":"Start a new conversation thread on the sled. Use this to share context from your AI session.","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Thread title"},"tool":{"type":"string","description":"Which tool created this"},"externalRef":{"type":"string","description":"External conversation ID"},"summary":{"type":"string","description":"Thread summary (markdown)"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Thread created"}}}},"/api/spaces/{slug}/threads/{id}":{"get":{"operationId":"getThread","summary":"Get thread with updates","description":"Returns a thread with its full observation/update history and linked entities.","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/slug"},{"$ref":"#/components/parameters/threadId"}],"responses":{"200":{"description":"Thread detail"},"404":{"description":"Not found"}}},"patch":{"operationId":"updateThread","summary":"Update a thread","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/slug"},{"$ref":"#/components/parameters/threadId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["active","paused","completed","archived"]},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"operationId":"archiveThread","summary":"Archive a thread","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/slug"},{"$ref":"#/components/parameters/threadId"}],"responses":{"200":{"description":"Archived"}}}},"/api/spaces/{slug}/threads/observe":{"post":{"operationId":"observeThread","summary":"Add an observation to a thread","description":"Record a decision, question, action, or observation on an existing thread. If threadId is omitted and a matching externalRef exists, it will be appended there.","tags":["Threads"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"threadId":{"type":"string","format":"uuid","description":"Target thread (omit to create new)"},"type":{"type":"string","enum":["observation","summary_refresh","decision","question","status_change","asset_produced"],"default":"observation"},"content":{"type":"string","description":"The observation content (markdown)"},"structured":{"type":"object","description":"Optional structured data"},"threadTitle":{"type":"string","description":"Title for new thread (required if no threadId)"},"threadTool":{"type":"string","enum":["claude","cursor","chatgpt","ai-studio","figma","slack","web","api","mcp"],"description":"Source tool (required if no threadId)"},"threadExternalRef":{"type":"string","description":"External reference (conversation URL, etc.)"}}}}}},"responses":{"200":{"description":"Observation recorded"}}}},"/api/spaces/{slug}/assets":{"get":{"operationId":"listAssets","summary":"List assets in a sled","tags":["Assets"],"parameters":[{"$ref":"#/components/parameters/slug"},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Asset list"}}},"post":{"operationId":"createAsset","summary":"Share an asset","description":"Share a spec, document, code snippet, or other artifact on the sled.","tags":["Assets"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","type"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["spec","document","code","image","design","config","reference","note"]},"content":{"type":"string","description":"Inline content (markdown, code, etc.)"},"tags":{"type":"array","items":{"type":"string"}},"threadId":{"type":"string","format":"uuid","description":"Link to originating thread"}}}}}},"responses":{"201":{"description":"Asset created"}}}},"/api/spaces/{slug}/assets/{id}":{"get":{"operationId":"getAsset","summary":"Get asset detail","tags":["Assets"],"parameters":[{"$ref":"#/components/parameters/slug"},{"$ref":"#/components/parameters/assetId"}],"responses":{"200":{"description":"Asset detail"},"404":{"description":"Not found"}}},"patch":{"operationId":"updateAsset","summary":"Update an asset","tags":["Assets"],"parameters":[{"$ref":"#/components/parameters/slug"},{"$ref":"#/components/parameters/assetId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated"}}}},"/api/spaces/{slug}/search":{"post":{"operationId":"search","summary":"Search the sled","description":"Semantic + full-text hybrid search across all threads and assets. Use this to find relevant context before starting work.","tags":["Search"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Natural language search query"},"entityTypes":{"type":"array","items":{"type":"string","enum":["thread","asset"]}},"tags":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"description":"Search results ranked by relevance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}}}}}}}},"/api/spaces/{slug}/links":{"post":{"operationId":"createLink","summary":"Link two items","description":"Create a relationship between threads and/or assets (implements, depends_on, related, supersedes, part_of).","tags":["Links"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromType","fromId","toType","toId","relationship"],"properties":{"fromType":{"type":"string","enum":["thread","asset"]},"fromId":{"type":"string","format":"uuid"},"toType":{"type":"string","enum":["thread","asset"]},"toId":{"type":"string","format":"uuid"},"relationship":{"type":"string","enum":["produced","depends_on","related","supersedes","references","informs"]}}}}}},"responses":{"201":{"description":"Link created"}}}},"/api/spaces/{slug}/sync":{"post":{"operationId":"syncConversation","summary":"Sync a conversation transcript","description":"Sync a full conversation transcript from an AI tool into a SLEDS thread. Deduplicates by conversation_id — safe to call repeatedly as the conversation grows. New messages are diffed and appended. Frost generates an AI summary after each sync.","tags":["Sync"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","messages"],"properties":{"conversation_id":{"type":"string","description":"Unique identifier for this conversation. Used for deduplication — pass the same ID on every sync of the same conversation."},"title":{"type":"string","description":"Conversation title. Updated on each sync if provided."},"source_tool":{"type":"string","enum":["claude","chatgpt","cursor","ai-studio","gemini","web","api"],"default":"claude","description":"Which AI tool is syncing this conversation."},"messages":{"type":"array","description":"Full conversation transcript. Always send the complete history — SLEDS diffs by count.","minItems":1,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant","system"]},"content":{"type":"string","description":"Message text"},"timestamp":{"type":"string","format":"date-time","description":"When the message was sent"}}}}}}}}},"responses":{"200":{"description":"Thread updated with new messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid","description":"SLEDS thread ID"},"messages_new":{"type":"integer","description":"Number of new messages added this sync"},"messages_total":{"type":"integer","description":"Total messages in thread"},"summary_queued":{"type":"boolean","description":"Whether Frost summary generation was queued"},"created":{"type":"boolean","description":"true if a new thread was created, false if updated"}}}}}}}},"201":{"description":"New thread created and synced"},"429":{"description":"Rate limit exceeded (30 syncs/min per API key)"}}}},"/api/spaces/{slug}/stream":{"get":{"operationId":"getStream","summary":"Activity stream","description":"Get recent events from the sled. Use for catching up on what happened since your last session.","tags":["Activity"],"parameters":[{"$ref":"#/components/parameters/slug"},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only events after this time"},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"types","in":"query","schema":{"type":"string"},"description":"Comma-separated event types"}],"responses":{"200":{"description":"Event stream","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StreamEvent"}}}}}}}}}},"/api/spaces/{slug}/sessions":{"get":{"operationId":"listSessions","summary":"Who's connected","description":"See which tools and users are currently connected to this sled.","tags":["Sessions"],"parameters":[{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Active sessions"}}},"post":{"operationId":"createSession","summary":"Register a connection","description":"Register your tool as connected to this sled.","tags":["Sessions"],"parameters":[{"$ref":"#/components/parameters/slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["toolName","displayName"],"properties":{"toolName":{"type":"string"},"displayName":{"type":"string"}}}}}},"responses":{"201":{"description":"Session created"}}}}},"tags":[{"name":"Spaces","description":"Sled (workspace) management"},{"name":"Threads","description":"Conversation threads — the core context unit"},{"name":"Assets","description":"Shared artifacts: specs, docs, code, configs"},{"name":"Search","description":"Semantic + full-text search across the sled"},{"name":"Links","description":"Knowledge graph — connect threads and assets"},{"name":"Sync","description":"Conversation transcript sync from AI tools"},{"name":"Activity","description":"Event stream and real-time updates"},{"name":"Sessions","description":"Active tool connections"}]}