{ "openapi": "3.1.0", "info": { "title": "Taproot AT Protocol Data API", "version": "1.0.0", "summary": "Read any AT Protocol identifier as clean JSON.", "description": "PDS-agnostic, read-only access to AT Protocol (atproto) data. Resolve a profile, a collection page, or a single record from an at:// URI, a handle, or a DID. An MCP server exposing these capabilities and more (27 read-only tools: backlinks, counts, account history, labels, lexicons, PDS/relay info, ...) is available at https://mcp.atproto.at/mcp (transport: streamable-http).", "license": { "name": "MIT" } }, "servers": [ { "url": "https://api.atproto.at/v1" } ], "x-mcp": { "url": "https://mcp.atproto.at/mcp", "transport": "streamable-http", "tools": [ "resolve", "get_profile", "get_record", "list_records", "get_backlinks", "list_backlink_records", "count_records", "search_accounts", "get_account_history", "search_lexicons", "resolve_lexicon", "describe_pds", "list_repos", "get_repo_status", "get_latest_commit", "verify_handle", "get_did_document", "get_app_link", "get_pds_directory_info", "get_relay_directory_info", "query_labels", "list_repos_by_collection", "count_repos_by_collection", "list_blobs", "get_blob_info", "list_labelers", "get_thread" ] }, "paths": { "/resolve": { "get": { "operationId": "resolveAtUri", "summary": "Resolve an AT Protocol identifier to JSON", "description": "Returns a profile, a collection page, or a single record depending on how specific `uri` is. Always pass the identifier in the `uri` query parameter (never the path).", "parameters": [ { "name": "uri", "in": "query", "required": true, "description": "An at:// URI (at:////), a bare handle, or a DID.", "schema": { "type": "string" }, "examples": { "handle": { "value": "alice.bsky.social" }, "collection": { "value": "at://alice.bsky.social/app.bsky.feed.post" }, "record": { "value": "at://alice.bsky.social/app.bsky.feed.post/3k2a..." } } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated enrichments: `schema` (lexicon), `backlinks` (constellation), and/or `profile` (the repo owner's display name, bio, and avatar URL).", "schema": { "type": "string", "example": "schema,backlinks,profile" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous collection response.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size for collection requests.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format. `json` (default) or `md` (Markdown). `Accept: text/markdown` also works. (`format` is accepted as a legacy alias.)", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Resolved data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Identity, record, or collection not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream PDS or resolution error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools": { "get": { "operationId": "listTools", "summary": "List all available tools", "description": "The full tool catalog (name, description, JSON-Schema input): the same payload the MCP server returns for tools/list, reachable by plain GET.", "responses": { "200": { "description": "The tool catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "/tools/resolve": { "get": { "operationId": "tool_resolve", "summary": "Resolve any AT Protocol identifier to JSON", "description": "Resolve any AT Protocol identifier to JSON. Accepts an at:// URI (at:////), a bare handle (alice.bsky.social), or a DID (did:plc:...). Returns a profile, a collection page, or a single record depending on how specific the input is. PDS-agnostic: works for any AT Protocol PDS, not just Bluesky. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "uri", "in": "query", "required": true, "description": "An at:// URI, a bare handle, or a DID.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Optional enrichments: 'schema' resolves the collection's lexicon; 'backlinks' lists who referenced the target; 'profile' adds the repo owner's display name, bio, and avatar URL.", "schema": { "type": "string", "description": "Comma-separated values." } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor (collections only).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-100, default 50). A cursor in the response means more pages exist.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_profile": { "get": { "operationId": "tool_get_profile", "summary": "Get an account's repository overview (handle, DID, PDS, and the list of collections it contains)", "description": "Get an account's repository overview (handle, DID, PDS, and the list of collections it contains). Input is a handle or DID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "actor", "in": "query", "required": true, "description": "A handle (alice.bsky.social) or DID (did:plc:...).", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Optional enrichments: 'schema' resolves the collection's lexicon; 'backlinks' lists who referenced the target; 'profile' adds the repo owner's display name, bio, and avatar URL.", "schema": { "type": "string", "description": "Comma-separated values." } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_record": { "get": { "operationId": "tool_get_record", "summary": "Fetch a single record by its full at:// URI (must include collection and rkey)", "description": "Fetch a single record by its full at:// URI (must include collection and rkey). Returns the record's value, CID, and resolved identity. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "uri", "in": "query", "required": true, "description": "Full at:// URI: at:////.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Optional enrichments: 'schema' resolves the collection's lexicon; 'backlinks' lists who referenced the target; 'profile' adds the repo owner's display name, bio, and avatar URL.", "schema": { "type": "string", "description": "Comma-separated values." } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/list_records": { "get": { "operationId": "tool_list_records", "summary": "List records in a collection for an account, with pagination", "description": "List records in a collection for an account, with pagination. Provide the repo (handle or DID) and the collection NSID (e.g. app.bsky.feed.post). (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "A handle or DID.", "schema": { "type": "string" } }, { "name": "collection", "in": "query", "required": true, "description": "Collection NSID, e.g. app.bsky.feed.post.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-100, default 50). A cursor in the response means more pages exist.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_backlinks": { "get": { "operationId": "tool_get_backlinks", "summary": "Index of who/what references a target,the inbound likes, reposts, quotes, replies, and follows,as COUNTS per category, via the Constellation backlink index", "description": "Index of who/what references a target,the inbound likes, reposts, quotes, replies, and follows,as COUNTS per category, via the Constellation backlink index. Target is a record's at:// URI or an account DID. This returns aggregate counts only; each category also includes a `source` string. To list the actual records and their author DIDs for one category (e.g. WHO liked a post), call list_backlink_records with that `source`. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "target", "in": "query", "required": true, "description": "A record at:// URI or a DID.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/list_backlink_records": { "get": { "operationId": "tool_list_backlink_records", "summary": "List the actual records (author DID + verified handle + at:// URI, newest first) that reference a target for ONE category,i.e", "description": "List the actual records (author DID + verified handle + at:// URI, newest first) that reference a target for ONE category,i.e. WHO liked, reposted, quoted, replied to, mentioned, or follows it. Workflow: call get_backlinks first to get a category `source`, then pass it here. To read WHAT a referencing record says (e.g. the text of a mention or reply), call get_record on its at:// URI. Author handles are resolved via identity resolution (verified), not search. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "target", "in": "query", "required": true, "description": "The referenced record at:// URI or account DID (same target passed to get_backlinks).", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": true, "description": "A category `source` from get_backlinks, e.g. app.bsky.feed.like:subject.uri.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor returned by a previous call (to get the next page).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-25, default 25). Use the returned cursor for the next page.", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/count_records": { "get": { "operationId": "tool_count_records", "summary": "Count the total records in an account's collection (e.g", "description": "Count the total records in an account's collection (e.g. how many likes a user has given). Scans server-side so you don't page manually. AT Protocol has no cheap exact count, so for very large collections this returns exact:false with a lower-bound count and a cursor,call again with that cursor and ADD the counts to keep going. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "A handle or DID.", "schema": { "type": "string" } }, { "name": "collection", "in": "query", "required": true, "description": "Collection NSID, e.g. app.bsky.feed.like.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Resume cursor from a prior capped (exact:false) count. The new count covers records AFTER it,add it to your previous total.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/search_accounts": { "get": { "operationId": "tool_search_accounts", "summary": "Search for AT Protocol accounts by handle or display name (paginated, via the Bluesky AppView app.bsky.actor.searchActors, so accounts unknown to that index may be missing)", "description": "Search for AT Protocol accounts by handle or display name (paginated, via the Bluesky AppView app.bsky.actor.searchActors, so accounts unknown to that index may be missing). Returns candidate accounts with DID + handle, to turn a name into a DID. Results are search CANDIDATES, not verified handle-to-DID mappings: call verify_handle before trusting that a handle really belongs to a DID (resolve/get_profile only confirm an account exists, not that the handle is authentic). (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "A handle fragment or display name, e.g. \"alice\".", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous call.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-100, default 50). A cursor in the response means more pages exist.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_account_history": { "get": { "operationId": "tool_get_account_history", "summary": "An account's history from its PLC audit log: handle changes, PDS migrations, signing-key rotations, and creation time", "description": "An account's history from its PLC audit log: handle changes, PDS migrations, signing-key rotations, and creation time. did:plc accounts only (did:web has no PLC log). Input is a handle or DID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "actor", "in": "query", "required": true, "description": "A handle or DID (did:plc).", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/search_lexicons": { "get": { "operationId": "tool_search_lexicons", "summary": "Browse or search the registry of published AT Protocol lexicon schemas", "description": "Browse or search the registry of published AT Protocol lexicon schemas. The response's `total` field is the exact registry size and `matched` is the exact match count. Substring matches the NSID or description (query 'profile' → anything containing 'profile'); prefix the query with a DOT for a suffix match (query '.profile' → only NSIDs ENDING in .profile, i.e. profile record types). Without a query, returns the total plus a sample. Results are paginated by `limit`; to see matches beyond the first page, call again with the `offset` printed at the end of the list. Use resolve_lexicon for a specific schema's full definition. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Optional substring to filter by, e.g. \"profile\" or \"app.bsky\".", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-100, default 50). A cursor in the response means more pages exist.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many matches (pagination). Use the offset value printed after a truncated list.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/resolve_lexicon": { "get": { "operationId": "tool_resolve_lexicon", "summary": "Explain what a record type means by resolving its lexicon schema", "description": "Explain what a record type means by resolving its lexicon schema. Input is a collection NSID (e.g. app.bsky.feed.post). Returns the schema's description and definition. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "nsid", "in": "query", "required": true, "description": "A collection NSID, e.g. app.bsky.feed.post.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/describe_pds": { "get": { "operationId": "tool_describe_pds", "summary": "Describe a Personal Data Server: its DID, whether registration requires an invite, the handle domains you can register there, and ToS/contact links", "description": "Describe a Personal Data Server: its DID, whether registration requires an invite, the handle domains you can register there, and ToS/contact links. Works for any PDS, not just Bluesky. Input is the PDS origin (e.g. https://pds.example.com). (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "pds", "in": "query", "required": true, "description": "A PDS origin URL, e.g. https://pds.example.com.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/list_repos": { "get": { "operationId": "tool_list_repos", "summary": "List the accounts (repositories) hosted on a PDS, via com.atproto.sync.listRepos: each repo's DID and active/takedown status, paginated", "description": "List the accounts (repositories) hosted on a PDS, via com.atproto.sync.listRepos: each repo's DID and active/takedown status, paginated. Answers 'who is hosted on this PDS?' / 'how many accounts does this PDS have?'. By default returns DIDs only (one request, large page — best for counting); pass enrich=true to also resolve handles (slower, smaller page). Input is the PDS origin (e.g. https://pds.example.com). Works for any PDS. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "pds", "in": "query", "required": true, "description": "A PDS origin URL, e.g. https://pds.example.com.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous call.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-1000, default 1000). With enrich=true the effective page is capped near 20 (each DID is resolved to a handle). Use the returned cursor for the next page.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "enrich", "in": "query", "required": false, "description": "Resolve each DID to its handle. Default false — returns DIDs only in ONE request (large page, the fast path for listing/counting). Set true only when you need handles (slower, smaller page).", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_repo_status": { "get": { "operationId": "tool_get_repo_status", "summary": "Liveness/moderation status of an account's repository: whether it is active, its current revision, and any takedown/suspended/deactivated/deleted state", "description": "Liveness/moderation status of an account's repository: whether it is active, its current revision, and any takedown/suspended/deactivated/deleted state. Answers 'has @alice been taken down?' which get_profile can't. Input is a handle or DID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "A handle or DID.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_latest_commit": { "get": { "operationId": "tool_get_latest_commit", "summary": "The current head commit of an account's repository (com.atproto.sync.getLatestCommit): its commit CID and revision", "description": "The current head commit of an account's repository (com.atproto.sync.getLatestCommit): its commit CID and revision. The cheapest way to fingerprint a repo or detect whether it changed since you last looked, without downloading data. Complements get_repo_status (which has the rev but not the commit CID). Input is a handle or DID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "A handle or DID.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/verify_handle": { "get": { "operationId": "tool_verify_handle", "summary": "Bidirectionally verify that a handle is really owned by its DID, via DNS TXT and HTTPS well-known", "description": "Bidirectionally verify that a handle is really owned by its DID, via DNS TXT and HTTPS well-known. Returns whether each method passed. Use this to check for impersonation/spoofing,search results and resolve give candidates, this gives cryptographic binding. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "A handle, e.g. alice.bsky.social.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_did_document": { "get": { "operationId": "tool_get_did_document", "summary": "Fetch the raw DID document for any DID or handle: all aliases (alsoKnownAs), every service entry (PDS, labeler, custom AppView), and verification methods", "description": "Fetch the raw DID document for any DID or handle: all aliases (alsoKnownAs), every service entry (PDS, labeler, custom AppView), and verification methods. Broader than get_profile, and works for did:web accounts. Input is a handle or DID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "actor", "in": "query", "required": true, "description": "A handle or DID.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_app_link": { "get": { "operationId": "tool_get_app_link", "summary": "Turn an at:// URI (or handle/DID) into shareable web links,a Bluesky/Blacksky app URL to open in a browser, plus the canonical PDS getRecord URL", "description": "Turn an at:// URI (or handle/DID) into shareable web links,a Bluesky/Blacksky app URL to open in a browser, plus the canonical PDS getRecord URL. Use when the user wants a clickable/pasteable link. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "uri", "in": "query", "required": true, "description": "An at:// URI, handle, or DID.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_pds_directory_info": { "get": { "operationId": "tool_get_pds_directory_info", "summary": "A cached health card for a PDS from pds.directory: version, DID, approximate user count, reachability, last-checked time, available domains, and which relays index it", "description": "A cached health card for a PDS from pds.directory: version, DID, approximate user count, reachability, last-checked time, available domains, and which relays index it. Input is the PDS hostname (e.g. pds.example.com). Best-effort/cached data. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "hostname", "in": "query", "required": true, "description": "A PDS hostname, e.g. pds.example.com.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_relay_directory_info": { "get": { "operationId": "tool_get_relay_directory_info", "summary": "A cached overview of a relay from firehose.directory: counts of PDSes it indexes (total/active/offline/banned) and total accounts", "description": "A cached overview of a relay from firehose.directory: counts of PDSes it indexes (total/active/offline/banned) and total accounts. Input is the relay hostname (e.g. bsky.network). Best-effort/cached data. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "hostname", "in": "query", "required": true, "description": "A relay hostname, e.g. bsky.network.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/query_labels": { "get": { "operationId": "tool_query_labels", "summary": "What moderation labels a labeler has applied to a subject (com.atproto.label.queryLabels),e.g", "description": "What moderation labels a labeler has applied to a subject (com.atproto.label.queryLabels),e.g. 'has @alice or this post been labeled spam/nsfw/hidden by labeler X?'. Anonymous and service-agnostic: the labeler's own service endpoint is found from its DID document (no hardcoded aggregator). Subject is a DID/handle (account labels) or an at:// URI (record labels); labeler is the handle or DID of a labeler service (e.g. moderation.bsky.app). (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "subject", "in": "query", "required": true, "description": "What to check: a DID/handle (account-level labels) or an at:// URI (record-level).", "schema": { "type": "string" } }, { "name": "labeler", "in": "query", "required": true, "description": "The labeler service to ask,a handle or DID, e.g. moderation.bsky.app.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous call.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-100, default 50). A cursor in the response means more pages exist.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/list_repos_by_collection": { "get": { "operationId": "tool_list_repos_by_collection", "summary": "Network-wide: which accounts publish a given collection/lexicon,e.g", "description": "Network-wide: which accounts publish a given collection/lexicon,e.g. 'who has an app.bsky.feed.generator (a custom feed)?' or who uses a custom lexicon. Via a relay's com.atproto.sync.listReposByCollection (anonymous). By default returns DIDs only (one request, large page); pass enrich=true to also resolve handles (slower, smaller page). For just a total, use count_repos_by_collection. NOTE: relay-served (defaults to the public Bluesky relay; pass `relay` to query another), not the account's own PDS. Pairs with search_lexicons / resolve_lexicon. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "collection", "in": "query", "required": true, "description": "A collection NSID, e.g. app.bsky.feed.generator.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous call.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-1000, default 1000). With enrich=true the effective page is capped near 20 (each DID is resolved to a handle). Use the returned cursor for the next page.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "relay", "in": "query", "required": false, "description": "Optional relay origin to query instead of the default, e.g. https://relay.example.com.", "schema": { "type": "string" } }, { "name": "enrich", "in": "query", "required": false, "description": "Resolve each DID to its handle. Default false — returns DIDs only in ONE request (large page, the fast path for listing/counting). Set true only when you need handles (slower, smaller page).", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/count_repos_by_collection": { "get": { "operationId": "tool_count_repos_by_collection", "summary": "Count how many accounts across the network publish a given collection/lexicon,e.g", "description": "Count how many accounts across the network publish a given collection/lexicon,e.g. 'how many accounts have an at.glean.subscription?'. Walks a relay's com.atproto.sync.listReposByCollection with NO per-account handle resolution, so it's cheap and returns an exact total for typical collections. For very large collections it returns exact:false with a cursor,call again with that cursor and ADD the counts (like count_records). Relay-served (defaults to the public Bluesky relay; pass `relay` for another). (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "collection", "in": "query", "required": true, "description": "A collection NSID, e.g. app.bsky.feed.generator.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Resume cursor from a previous exact:false response.", "schema": { "type": "string" } }, { "name": "relay", "in": "query", "required": false, "description": "Optional relay origin to query instead of the default, e.g. https://relay.example.com.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/list_blobs": { "get": { "operationId": "tool_list_blobs", "summary": "List the blobs (uploaded media/attachments,images, video, etc.) hosted in an account's repository, via com.atproto.sync.listBlobs", "description": "List the blobs (uploaded media/attachments,images, video, etc.) hosted in an account's repository, via com.atproto.sync.listBlobs. Returns each blob's CID and its canonical PDS getBlob URL (PDS-native, works for any PDS,not a CDN). Answers 'what media does this account host?'. Records reference blobs by CID; use this (or get_blob_info) to turn a CID into a fetchable URL. Input is a handle or DID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "A handle or DID.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous call.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-100, default 50). A cursor in the response means more pages exist.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_blob_info": { "get": { "operationId": "tool_get_blob_info", "summary": "Get metadata for a single blob: its canonical PDS getBlob URL plus a best-effort content-type and byte size (via a HEAD request)", "description": "Get metadata for a single blob: its canonical PDS getBlob URL plus a best-effort content-type and byte size (via a HEAD request). Returns the URL, never the bytes. Use to turn a blob ref (CID) found in a record into a downloadable link and learn what it is. Input is the owning repo (handle or DID) and the blob CID. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "A handle or DID (the blob's owning repo).", "schema": { "type": "string" } }, { "name": "cid", "in": "query", "required": true, "description": "The blob CID (e.g. bafkrei...), as found in a record's blob ref.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/list_labelers": { "get": { "operationId": "tool_list_labelers", "summary": "List the labeler (moderation) services known to the labeler relay,each labeler's DID, resolved handle, and service endpoint", "description": "List the labeler (moderation) services known to the labeler relay,each labeler's DID, resolved handle, and service endpoint. The discovery step BEFORE query_labels, which needs a labeler DID/handle up front: use this to find moderation.bsky.app and any third-party/regional labelers, then pass one to query_labels. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous call.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-20, default 20). Use the returned cursor for the next page.", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools/get_thread": { "get": { "operationId": "tool_get_thread", "summary": "Reconstruct the conversation around a post: its ancestor chain up to the thread root (following reply.parent, root-first) PLUS a bounded descendant reply TREE,replies, replies-to-replies, and so on, each tagged with its depth and parent,walked breadth-first and capped for cost", "description": "Reconstruct the conversation around a post: its ancestor chain up to the thread root (following reply.parent, root-first) PLUS a bounded descendant reply TREE,replies, replies-to-replies, and so on, each tagged with its depth and parent,walked breadth-first and capped for cost. NOTE: descendant expansion assumes the Bluesky reply model (app.bsky.feed.post with reply.parent); ancestor walking follows reply.parent generically, but the reply tree is specific to that lexicon and will be empty for record types that model replies differently. Answers 'show me this whole conversation / what is this replying to?'. If the tree is truncated, use list_backlink_records on a specific post's URI to expand it further. Input is a post's at:// URI. (Array parameters are passed comma-separated. Add ?fmt=md for the text rendering.)", "parameters": [ { "name": "uri", "in": "query", "required": true, "description": "A post's full at:// URI: at:///app.bsky.feed.post/.", "schema": { "type": "string" } }, { "name": "fmt", "in": "query", "required": false, "description": "Response format: `json` (default) or `md` (Markdown). `Accept: text/markdown` also works.", "schema": { "type": "string", "enum": [ "json", "md" ] } } ], "responses": { "200": { "description": "Tool result (the tool's structured payload).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid argument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown tool or subject not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited. Wait for the Retry-After header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "Upstream PDS timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "schemas": { "Identity": { "type": "object", "properties": { "did": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "pds": { "type": "string", "format": "uri" } }, "required": [ "did", "handle", "pds" ] }, "Envelope": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "profile", "collection", "record" ] }, "uri": { "type": "string", "description": "Canonical at:// URI built from the resolved DID." }, "identity": { "$ref": "#/components/schemas/Identity" }, "collection": { "type": "string" }, "rkey": { "type": "string" }, "data": { "description": "A record, a {records,cursor} page, or repo info.", "type": "object", "additionalProperties": true }, "enrich": { "type": "object", "description": "Present when ?include= was used.", "additionalProperties": true }, "_links": { "type": "object", "additionalProperties": { "type": "string" } }, "_docs": { "type": "string", "format": "uri" } }, "required": [ "type", "uri", "identity", "data", "_links" ] }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string", "description": "An actionable next step to recover." } }, "required": [ "code", "message" ] }, "status": { "type": "integer" }, "_docs": { "type": "string", "format": "uri" } }, "required": [ "error", "status" ] } } } }