{"openapi":"3.1.0","info":{"title":"Assemble API","version":"1.0.0","description":"Public REST API for external agents and integrations. Push draft artifacts and search validated workspace intelligence. Authenticate with a workspace API key as a Bearer token."},"servers":[{"url":"https://poc.assemble.site.avrdevelopment.com"}],"tags":[{"name":"Artifacts","description":"Push draft artifacts and search or fetch validated workspace artifacts."},{"name":"Feedback","description":"Validation outcomes for pushed artifacts — what humans validated or disputed, and why."},{"name":"Briefing","description":"The workspace's standing context, directives, and active rules and definitions."},{"name":"Memories","description":"Semantic recall over the workspace's accumulated memories."},{"name":"Data Sources","description":"Schemas, table annotations, proven query patterns, and error learnings — the map of the data, never the credentials."},{"name":"Skills","description":"Reusable procedures (SKILL.md bundles) agents can follow."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace API key (Settings → API Keys)"}},"schemas":{"CreateArtifactResponse":{"type":"object","properties":{"artifactId":{"type":"string"},"status":{"type":"string","enum":["draft"]}},"required":["artifactId","status"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"CreateArtifactRequest":{"type":"object","properties":{"summary":{"type":"string","description":"One-line headline for the artifact","example":"EMEA churn doubled in May"},"why":{"type":"string","description":"Why this analysis matters"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence score between 0 and 1 (numeric strings are coerced)","example":0.85},"confidenceExplanation":{"type":"string","description":"Reasoning behind the confidence score"},"recommendation":{"type":["string","null"]},"content":{"description":"Artifact body (markdown string or structured object)"},"dataSources":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ArtifactDataSource"}},"codeExecuted":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ArtifactCodeExecuted"}},"sourceSystem":{"type":["string","null"],"description":"Identifier of the system that produced this artifact","example":"my-agent"},"keyFindings":{"type":["array","null"],"items":{"type":"string"}},"recommendations":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ArtifactRecommendation"}}},"required":["summary","why","confidence","confidenceExplanation"]},"ArtifactDataSource":{"type":"object","properties":{"type":{"type":"string","enum":["file","database","external"]},"name":{"type":"string"},"id":{"type":"string"}},"required":["type","name"]},"ArtifactCodeExecuted":{"type":"object","properties":{"language":{"type":"string"},"code":{"type":"string"},"output":{"type":"string"},"timestamp":{"type":"number"},"title":{"type":"string"},"toolName":{"type":"string"}},"required":["language","code"]},"ArtifactRecommendation":{"type":"object","properties":{"text":{"type":"string"},"type":{"type":"string","enum":["recommendation","warning","info"]}},"required":["text","type"]},"SearchArtifactsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactSummary"}}},"required":["results"]},"ArtifactSummary":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string"},"why":{"type":"string"},"recommendation":{"type":"string"},"confidence":{"type":"number"},"keyFindings":{"type":"array","items":{"type":"string"}},"dataSources":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactDataSource"}},"createdAt":{"type":"number"},"validatedAt":{"type":"number"},"score":{"type":"number","description":"Semantic-search relevance score"}},"required":["id","summary","why","confidence","dataSources","createdAt","score"]},"ArtifactDetail":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string"},"why":{"type":"string"},"recommendation":{"type":"string"},"confidence":{"type":"number"},"keyFindings":{"type":"array","items":{"type":"string"}},"dataSources":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactDataSource"}},"createdAt":{"type":"number"},"validatedAt":{"type":"number"},"confidenceExplanation":{"type":"string"},"content":{"description":"Artifact body, truncated to 20k characters"},"contentTruncated":{"type":"boolean"},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactRecommendation"}},"codeExecuted":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactCodeExecuted"}},"sourceSystem":{"type":"string"},"previousArtifactId":{"type":"string"}},"required":["id","summary","why","confidence","dataSources","createdAt","confidenceExplanation","contentTruncated"]},"FeedbackResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackItem"}},"nextCursor":{"type":["string","null"],"description":"Pass back as ?cursor= for the next page; null when there are no more results. Note: items.length < limit does NOT imply the end — only nextCursor: null does."}},"required":["items","nextCursor"]},"FeedbackItem":{"type":"object","properties":{"artifactId":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["draft","validated","disputed"]},"disputeReason":{"type":"string","description":"Why a human disputed this artifact — the lesson to learn from"},"validatedAt":{"type":"number"},"validatedBy":{"type":"string"},"confidence":{"type":"number"},"createdBy":{"type":"string"},"createdAt":{"type":"number"}},"required":["artifactId","summary","status","confidence","createdBy","createdAt"]},"BriefingResponse":{"type":"object","properties":{"workspace":{"type":"object","properties":{"name":{"type":"string"},"context":{"type":["string","null"],"description":"Standing workspace context — injected into every internal agent prompt; treat it the same way"}},"required":["name","context"]},"directives":{"type":"array","items":{"$ref":"#/components/schemas/BriefingDirective"},"description":"Hard rules the workspace's agents must always follow"},"directivesAvailable":{"type":"boolean","description":"false when the directive store is unavailable on this deployment — directives may exist but could not be fetched"},"memories":{"type":"array","items":{"$ref":"#/components/schemas/BriefingMemory"},"description":"Active workspace rules and definitions from the memory ledger, newest first (capped at 200)"}},"required":["workspace","directives","directivesAvailable","memories"]},"BriefingDirective":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"}},"required":["id","name","content"]},"BriefingMemory":{"type":"object","properties":{"type":{"type":"string","enum":["rule","definition"]},"statement":{"type":"string"},"goingForward":{"type":"string","description":"How to apply this memory going forward"},"createdAt":{"type":"number"}},"required":["type","statement","createdAt"]},"RecallMemoriesResponse":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/MemoryHit"}}},"required":["hits"]},"MemoryHit":{"type":"object","properties":{"memoryId":{"type":"string"},"type":{"type":"string","description":"Memory type: preference | rule | correction | definition | finding | context"},"statement":{"type":"string"},"goingForward":{"type":"string"},"context":{"type":"string","description":"Why this memory matched, when the store provides it"}},"required":["memoryId","type","statement"]},"DataSourcesResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DataSourceItem"}}},"required":["items"]},"DataSourceItem":{"type":"object","properties":{"name":{"type":"string"},"connectorType":{"type":"string","enum":["postgres","mysql","sqlserver","clickhouse","databricks"]},"status":{"type":"string","enum":["connected","error","disconnected"]},"schema":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"columnName":{"type":"string"},"dataType":{"type":"string"}},"required":["columnName","dataType"]}}},"required":["tableName","columns"]}},"tableAnnotations":{"type":"array","items":{"$ref":"#/components/schemas/TableAnnotation"}},"createdAt":{"type":"number"}},"required":["name","connectorType","status","createdAt"]},"TableAnnotation":{"type":"object","properties":{"tableName":{"type":"string"},"description":{"type":"string"},"useCases":{"type":"array","items":{"type":"string"}},"gotchas":{"type":"array","items":{"type":"string"},"description":"Known traps in this table — read before querying it"}},"required":["tableName","description","useCases","gotchas"]},"QueryIntelligenceResponse":{"type":"object","properties":{"patterns":{"type":"array","items":{"$ref":"#/components/schemas/QueryPattern"}},"errorLearnings":{"type":"array","items":{"$ref":"#/components/schemas/ErrorLearning"}}},"required":["patterns","errorLearnings"]},"QueryPattern":{"type":"object","properties":{"question":{"type":"string","description":"The intent this SQL has successfully answered"},"sql":{"type":"string"},"resultSummary":{"type":"string"},"successCount":{"type":"number","description":"How many times this pattern has answered the question"},"lastUsedAt":{"type":"number"}},"required":["question","sql","successCount"]},"ErrorLearning":{"type":"object","properties":{"failedSql":{"type":"string"},"errorMessage":{"type":"string"},"learning":{"type":"string","description":"The lesson — what to avoid or do instead"},"createdAt":{"type":"number"}},"required":["failedSql","errorMessage","learning","createdAt"]},"SkillsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SkillItem"}}},"required":["items"]},"SkillItem":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"number"},"source":{"type":"string","enum":["uploaded","authored"]},"official":{"type":"boolean"},"allowedTools":{"type":"array","items":{"type":"string"}},"compatibility":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/SkillFileEntry"}}},"required":["name","description","version","source","official","files"]},"SkillFileEntry":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"},"kind":{"type":"string","enum":["markdown","script","text","binary"]}},"required":["path","size","kind"]},"SkillFileResponse":{"type":"object","properties":{"path":{"type":"string"},"kind":{"type":"string","enum":["markdown","script","text","binary"]},"size":{"type":"number"},"content":{"type":["string","null"],"description":"Inline content for text-like files; null for binaries"},"url":{"type":["string","null"],"description":"Time-limited download URL for binaries; null otherwise"}},"required":["path","kind","size","content","url"]}},"parameters":{}},"paths":{"/api/v1/artifacts":{"post":{"summary":"Push an artifact","description":"Create a draft artifact in the workspace tied to the API key. Drafts go through human validation before they surface to other consumers.","tags":["Artifacts"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArtifactRequest"}}}},"responses":{"201":{"description":"Artifact created as draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArtifactResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Search validated artifacts","description":"Semantic search over validated artifacts in the workspace tied to the API key.","tags":["Artifacts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Natural-language search over validated artifacts","example":"churn drivers"},"required":true,"description":"Natural-language search over validated artifacts","name":"query","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"description":"Maximum number of results (1-20, default 10)"},"required":false,"description":"Maximum number of results (1-20, default 10)","name":"limit","in":"query"}],"responses":{"200":{"description":"Ranked search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchArtifactsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}":{"get":{"summary":"Get an artifact","description":"Fetch a validated artifact by id, including content (truncated to 20k chars), code executed, and provenance.","tags":["Artifacts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Artifact id"},"required":true,"description":"Artifact id","name":"id","in":"path"}],"responses":{"200":{"description":"Artifact detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactDetail"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, not validated, or not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback":{"get":{"summary":"Read validation outcomes","description":"How humans judged pushed artifacts: validated, disputed (with the reason), or still draft. Defaults to artifacts pushed by the calling API key; pass audience=workspace for all external pushes.","tags":["Feedback"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Opaque cursor from a previous response's nextCursor. Omit for the first page."},"required":false,"description":"Opaque cursor from a previous response's nextCursor. Omit for the first page.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"},"required":false,"description":"Page size (1-100, default 20)","name":"limit","in":"query"},{"schema":{"type":"string","enum":["draft","validated","disputed"],"description":"Only outcomes with this status"},"required":false,"description":"Only outcomes with this status","name":"status","in":"query"},{"schema":{"type":"string","enum":["mine","workspace"],"description":"mine (default): artifacts pushed by this API key. workspace: all externally-pushed artifacts — shared lessons from every integration's outcomes."},"required":false,"description":"mine (default): artifacts pushed by this API key. workspace: all externally-pushed artifacts — shared lessons from every integration's outcomes.","name":"audience","in":"query"}],"responses":{"200":{"description":"Validation outcomes, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/briefing":{"get":{"summary":"Get the workspace briefing","description":"Everything an external agent should read before doing work: standing workspace context, hard directives, and the org's active rules and definitions.","tags":["Briefing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The workspace briefing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memories":{"get":{"summary":"Recall workspace memories","description":"Semantic search over the workspace's accumulated memories (rules, definitions, findings, corrections). Returns ranked hits filtered to currently-active memories.","tags":["Memories"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Natural-language query over the workspace's memories","example":"how do we define active users"},"required":true,"description":"Natural-language query over the workspace's memories","name":"query","in":"query"}],"responses":{"200":{"description":"Ranked memory hits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallMemoriesResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-sources":{"get":{"summary":"List data sources","description":"Connected data sources with their schemas and table annotations (descriptions, use cases, gotchas). Metadata only — no credentials, no query execution.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Data sources in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataSourcesResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-sources/{name}/query-intelligence":{"get":{"summary":"Get query intelligence","description":"Proven SQL patterns and error learnings for a data source, matched to your question — what has worked before and which mistakes to avoid.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Data source name (URL-encoded)"},"required":true,"description":"Data source name (URL-encoded)","name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"description":"What you're trying to compute","example":"weekly churn in EMEA"},"required":true,"description":"What you're trying to compute","name":"question","in":"query"}],"responses":{"200":{"description":"Matched patterns and learnings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryIntelligenceResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown data source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills":{"get":{"summary":"List skills","description":"Enabled skills in the workspace — reusable procedures (SKILL.md bundles) an agent can read and follow.","tags":["Skills"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Enabled skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{name}/files":{"get":{"summary":"Read a skill file","description":"Fetch one file from a skill bundle by its path (e.g. ?path=SKILL.md). Text files are returned inline; binaries as a signed URL.","tags":["Skills"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Skill name"},"required":true,"description":"Skill name","name":"name","in":"path"},{"schema":{"type":"string","minLength":1,"description":"File path inside the bundle, e.g. SKILL.md","example":"SKILL.md"},"required":true,"description":"File path inside the bundle, e.g. SKILL.md","name":"path","in":"query"}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillFileResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown skill or file path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"File storage was unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}