{"openapi":"3.1.0","info":{"title":"Department of Creative Affairs (DCA) API","version":"1.0.0","summary":"Search the DCA directory of independent creative agencies.","description":"Read-only access to the published DCA agency directory, plus a Model Context Protocol (MCP) server. Use it to find independent creative agencies by discipline, sector, location, size or free text, and to read an agency profile with its published work. The directory JSON and the public MCP endpoint need no key. The member MCP endpoint uses OAuth 2.0 and edits only agencies the signed-in account belongs to. Agent summary: https://preview.thedca.co/llms.txt.","contact":{"name":"DCA","email":"hi@thedca.co","url":"https://preview.thedca.co/contact"},"termsOfService":"https://preview.thedca.co/legal/terms"},"servers":[{"url":"https://preview.thedca.co","description":"DCA"}],"externalDocs":{"description":"DCA for agents (llms.txt)","url":"https://preview.thedca.co/llms.txt"},"tags":[{"name":"Directory","description":"The published agency catalogue."},{"name":"MCP","description":"Model Context Protocol endpoints (Streamable HTTP, JSON-RPC 2.0)."},{"name":"Discovery","description":"Files that describe the site to agents and crawlers."}],"paths":{"/api/agencies.json":{"get":{"operationId":"listAgencies","tags":["Directory"],"summary":"Search published agencies","description":"Returns every published agency that matches the filters, ranked by `sort`, with the facet values available for further filtering. Filter values are the labels shown in `facets` (matched case-insensitively). Unknown values match nothing rather than failing.","parameters":[{"name":"query","in":"query","required":false,"description":"Free text matched against agency names, summaries, published work, team bios and clients. `q` is accepted as an alias.","schema":{"type":"string","maxLength":200},"example":"sustainability campaign"},{"name":"services","in":"query","required":false,"description":"Discipline labels, for example `Brand` or `Digital & Experience`. Repeat the parameter or separate values with commas. Several values widen the match (OR); combining different filters narrows it (AND).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"specialisms","in":"query","required":false,"description":"Specialism labels. Repeat the parameter or separate values with commas. Several values widen the match (OR); combining different filters narrows it (AND).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"sectors","in":"query","required":false,"description":"Client sector labels, for example `Financial services`. Repeat the parameter or separate values with commas. Several values widen the match (OR); combining different filters narrows it (AND).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"countries","in":"query","required":false,"description":"Headquarter or office countries. Repeat the parameter or separate values with commas. Several values widen the match (OR); combining different filters narrows it (AND).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"cities","in":"query","required":false,"description":"Headquarter or office cities. Repeat the parameter or separate values with commas. Several values widen the match (OR); combining different filters narrows it (AND).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"sizes","in":"query","required":false,"description":"Headcount band slugs. Repeat the parameter or separate values with commas. Several values widen the match (OR); combining different filters narrows it (AND).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["1-10","11-25","26-50","51-100","101-250","250+"]}}},{"name":"verified","in":"query","required":false,"description":"Set to `1` to keep only DCA Verified agencies.","schema":{"type":"string","enum":["1"]}},{"name":"sort","in":"query","required":false,"description":"Result order. Defaults to `recently-updated`; `best-fit` ranks by relevance to `query`.","schema":{"type":"string","enum":["best-fit","a-z","most-case-studies","recently-updated","newest"],"default":"recently-updated"}}],"responses":{"200":{"description":"The matching agencies and the filters that produced them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryResponse"}}}},"503":{"description":"The catalogue is temporarily unavailable. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp/public":{"post":{"operationId":"callPublicMcp","tags":["MCP"],"summary":"Call the public MCP server","description":"MCP Streamable HTTP endpoint (JSON-RPC 2.0). No authentication. Tools: `search_agencies` (query, services, sectors, limit 1-50) and `get_agency` (slug). Send `initialize` first, then `tools/list` and `tools/call`. Send `Accept: application/json, text/event-stream`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"A JSON-RPC response, as JSON or a single-event SSE stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"The body is not a valid JSON-RPC request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}}},"/mcp/manage":{"post":{"operationId":"callManageMcp","tags":["MCP"],"summary":"Call the member MCP server","description":"MCP Streamable HTTP endpoint for agency members. Requires an OAuth 2.0 bearer token for this resource. `agency:read` reads the member's agency, case studies and reviews; `agency:write` updates them and publishes. An unauthenticated call returns 401 with a `WWW-Authenticate` challenge naming the protected resource metadata.","security":[{"oauth2":["agency:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"A JSON-RPC response, as JSON or a single-event SSE stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"403":{"description":"The token lacks the scope the call needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsText","tags":["Discovery"],"summary":"Read the agent summary","description":"What DCA is, when an agent should use it, and how to call it, in the llms.txt format.","responses":{"200":{"description":"Markdown text.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"operationId":"getSitemap","tags":["Discovery"],"summary":"List every public page","responses":{"200":{"description":"A sitemaps.org URL set.","content":{"application/xml":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Authorization code with PKCE (S256). Clients may register dynamically at https://preview.thedca.co/api/auth/oauth2/register. Metadata: https://preview.thedca.co/.well-known/oauth-authorization-server/api/auth.","flows":{"authorizationCode":{"authorizationUrl":"https://preview.thedca.co/api/auth/oauth2/authorize","tokenUrl":"https://preview.thedca.co/api/auth/oauth2/token","refreshUrl":"https://preview.thedca.co/api/auth/oauth2/token","scopes":{"agency:read":"Read the agencies your account belongs to.","agency:write":"Edit and publish the agencies your account belongs to.","offline_access":"Receive a refresh token."}}}}},"schemas":{"Error":{"type":"object","description":"Every JSON error has this shape.","required":["code","message","httpStatus"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","examples":["DCA_API_404_NOT_FOUND"]},"tag":{"type":"string"},"category":{"type":"string"},"title":{"type":"string","description":"The HTTP reason phrase."},"message":{"type":"string","description":"What went wrong, for a person or an agent."},"hint":{"type":"string","description":"What to do next."},"httpStatus":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"},"docs":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"related":{"type":"array","items":{"type":"string"}}}}}},"DirectoryResponse":{"type":"object","required":["site","links","filters","total","shown","facets","agencies"],"properties":{"site":{"type":"object","properties":{"name":{"type":"string"},"abbreviation":{"type":"string"},"description":{"type":"string"}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"html":{"type":"string","format":"uri","description":"The same view as a web page, for citing to a person."},"documentation":{"type":"string","format":"uri"},"sitemap":{"type":"string","format":"uri"}}},"querySyntax":{"type":"object","description":"A short, human-readable restatement of the query parameters."},"filters":{"type":"object","description":"The filters the server applied, after normalisation.","properties":{"services":{"type":"array","items":{"type":"string"}},"specialisms":{"type":"array","items":{"type":"string"}},"sectors":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"type":"string"}},"cities":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"verified":{"type":"boolean"},"query":{"type":"string"},"sort":{"type":"string","enum":["best-fit","a-z","most-case-studies","recently-updated","newest"]}}},"total":{"type":"integer","description":"Published agencies before filtering."},"shown":{"type":"integer","description":"Agencies returned."},"facets":{"type":"object","description":"Values available to filter on.","properties":{"services":{"type":"array","items":{"type":"string"}},"specialisms":{"type":"array","items":{"type":"string"}},"sectors":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"}}}},"verified":{"type":"integer","description":"How many DCA Verified agencies match."}}},"agencies":{"type":"array","items":{"$ref":"#/components/schemas/Agency"}}}},"Agency":{"type":"object","required":["slug","name","url"],"properties":{"slug":{"type":"string","description":"Stable identifier; pass to the `get_agency` MCP tool."},"name":{"type":"string"},"summary":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"The public profile page. Cite this."},"services":{"type":"array","items":{"type":"string"}},"specialisms":{"type":"array","items":{"type":"string"}},"sectors":{"type":"array","items":{"type":"string"}},"sizeBand":{"type":["string","null"],"enum":["1-10","11-25","26-50","51-100","101-250","250+",null]},"location":{"type":"object","properties":{"hqCity":{"type":["string","null"]},"hqCountry":{"type":["string","null"]},"offices":{"type":"array","items":{}}}},"verified":{"type":"boolean","description":"DCA Verified: DCA verified the agency itself, or it has one or more completed client references."},"verifiedByDca":{"type":"boolean","description":"Present and true when DCA verified the agency after its own assessment, with or without references."},"verifiedReferences":{"type":"integer","description":"Client references DCA has verified."},"clients":{"type":"array","items":{"type":"string"}},"works":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"client":{"type":["string","null"]},"sectors":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri"}}}},"matches":{"type":"array","description":"Why the agency matched the query, with the page that supports it.","items":{"type":"object","properties":{"kind":{"type":"string"},"value":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"}}}},"imageUrl":{"type":["string","null"],"format":"uri"},"tier":{"type":["string","null"]},"workCount":{"type":"integer"},"publishedAt":{"type":["string","null"],"format":"date-time"}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer"]},"method":{"type":"string","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object"}},"examples":[{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_agencies","arguments":{"query":"brand identity","sectors":["Food"],"limit":5}}}]},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","integer","null"]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}}}}}}}}