{
  "openapi": "3.1.0",
  "info": {
    "title": "Silicon Developer API",
    "version": "1.0.0",
    "summary": "Search and read the Silicon Apps and Silicon Accounts docs, and reach the platform's MCP server.",
    "description": "The public API of developers.teamofsilicons.com. Every endpoint is a read and needs no sign-in.\n\nRate limits: the docs API allows 120 requests and /mcp 60 requests every 60 seconds from one client address. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a request over the limit gets 429 with Retry-After.\n\nErrors are JSON: {\"error\": {\"code\", \"message\", \"hint\"}}. The code is stable, the message says what happened, the hint says what to do.\n\nTo act on the platform (create apps, publish, sign Carbons and Silicons in, verify apps), use the Silicon Apps and Silicon Accounts APIs linked in x-related-apis.",
    "contact": {
      "name": "Team of Silicons",
      "url": "https://teamofsilicons.com",
      "email": "lords@teamofsilicons.com"
    }
  },
  "servers": [
    {
      "url": "https://developers.teamofsilicons.com"
    }
  ],
  "externalDocs": {
    "description": "Silicon Developer docs",
    "url": "https://developers.teamofsilicons.com/docs"
  },
  "x-related-apis": [
    {
      "name": "Silicon Accounts API",
      "url": "https://accounts.teamofsilicons.com/v1",
      "openapi": "https://accounts.teamofsilicons.com/openapi.json",
      "docs": "https://developers.teamofsilicons.com/docs/accounts/reference/api"
    },
    {
      "name": "Silicon Apps API",
      "url": "https://apps.teamofsilicons.com/v1",
      "openapi": "https://apps.teamofsilicons.com/openapi.json",
      "docs": "https://developers.teamofsilicons.com/docs/apps/reference/api"
    }
  ],
  "x-agent-card": "https://developers.teamofsilicons.com/.well-known/agent.json",
  "x-llms-txt": "https://developers.teamofsilicons.com/llms.txt",
  "tags": [
    {
      "name": "Docs",
      "description": "The developer docs as JSON."
    },
    {
      "name": "MCP",
      "description": "The Model Context Protocol server."
    },
    {
      "name": "Agent files",
      "description": "Text and JSON files for agents and crawlers."
    }
  ],
  "paths": {
    "/api/docs/search": {
      "get": {
        "tags": [
          "Docs"
        ],
        "operationId": "searchDocs",
        "summary": "Search the docs",
        "description": "Ranks pages and their h2 and h3 sections. Every word must appear; titles and headings rank above text, whole words above parts, the exact phrase above scattered words. At most four sections of one page.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "What to look for: a task, a command, an endpoint or an error code.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "example": "publish an app"
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "description": "Only one product: apps (Silicon Apps) or accounts (Silicon Accounts).",
            "schema": {
              "type": "string",
              "enum": [
                "apps",
                "accounts"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only one kind of page: start (guides), learn (explanations), reference, or overview.",
            "schema": {
              "type": "string",
              "enum": [
                "start",
                "learn",
                "reference",
                "overview"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many results to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked results.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/docs/pages": {
      "get": {
        "tags": [
          "Docs"
        ],
        "operationId": "listDocs",
        "summary": "List the docs pages",
        "description": "Every page in reading order, optionally only one product or kind.",
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "description": "Only one product: apps (Silicon Apps) or accounts (Silicon Accounts).",
            "schema": {
              "type": "string",
              "enum": [
                "apps",
                "accounts"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only one kind of page: start (guides), learn (explanations), reference, or overview.",
            "schema": {
              "type": "string",
              "enum": [
                "start",
                "learn",
                "reference",
                "overview"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The pages.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/docs/pages/{product}/{path}": {
      "get": {
        "tags": [
          "Docs"
        ],
        "operationId": "readDoc",
        "summary": "Read one docs page",
        "description": "One page with its Markdown as written, headings, related pages and neighbours. The path may hold slashes (start/publish, reference/api/oauth) and may end in .md; leave it out for the product's overview. /api/docs/pages/index is the docs landing page.",
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "apps",
                "accounts"
              ]
            }
          },
          {
            "name": "path",
            "in": "path",
            "required": true,
            "allowReserved": true,
            "description": "The page's path inside the product.",
            "schema": {
              "type": "string"
            },
            "example": "start/publish"
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageDetail"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "tags": [
          "Docs"
        ],
        "operationId": "docsApiIndex",
        "summary": "What the docs API offers",
        "responses": {
          "200": {
            "description": "The endpoints, with links.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "operationId": "mcp",
        "summary": "MCP server (Streamable HTTP)",
        "description": "Stateless MCP over Streamable HTTP. Protocol versions 2025-06-18, 2025-03-26, 2024-11-05. Methods: initialize, ping, tools/list, tools/call. Tools: search_docs, read_doc, list_docs, search_apps, get_app, check_app_id, check_account_id (all read-only). Answers are JSON, or a one-event SSE stream when Accept names only text/event-stream. Notifications get 202. GET answers 405: the server opens no stream of its own.",
        "parameters": [
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "2025-06-18",
                "2025-03-26",
                "2024-11-05"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/JsonRpcRequest"
                  },
                  {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/JsonRpcRequest"
                    },
                    "maxItems": 32
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The JSON-RPC answer.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/JsonRpcResponse"
                      }
                    }
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Accepted: the body held only notifications or responses."
          },
          "400": {
            "description": "Not JSON, not JSON-RPC, or an unsupported MCP-Protocol-Version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this address.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "Agent files"
        ],
        "operationId": "llmsTxt",
        "summary": "The docs for language models, in short (llmstxt.org)",
        "responses": {
          "200": {
            "description": "Markdown text.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "tags": [
          "Agent files"
        ],
        "operationId": "llmsFullTxt",
        "summary": "Everything in one text file",
        "responses": {
          "200": {
            "description": "Markdown text.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "tags": [
          "Agent files"
        ],
        "operationId": "agentCard",
        "summary": "The A2A agent card",
        "responses": {
          "200": {
            "description": "The agent card.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": [
          "Agent files"
        ],
        "operationId": "sitemap",
        "summary": "Every public page",
        "responses": {
          "200": {
            "description": "A sitemap.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit-Limit": {
        "description": "Requests allowed in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left in this window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before trying again.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "A parameter is missing or not valid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Nothing lives at this address.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too many requests from this address.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalError": {
        "description": "The server failed to answer.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "code": {
                "type": "string",
                "examples": [
                  "missing_query",
                  "invalid_product",
                  "page_not_found",
                  "rate_limited"
                ]
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              }
            }
          }
        }
      },
      "Product": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "apps",
          "accounts",
          null
        ]
      },
      "Kind": {
        "type": "string",
        "enum": [
          "start",
          "learn",
          "reference",
          "overview"
        ]
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "title",
          "section",
          "url",
          "path",
          "markdown_url",
          "product",
          "kind",
          "group",
          "snippet"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "The page's title."
          },
          "section": {
            "type": [
              "string",
              "null"
            ],
            "description": "The section's heading, or null for the page itself."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "path": {
            "type": "string",
            "description": "The address on this site, with the section's anchor."
          },
          "markdown_url": {
            "type": "string",
            "format": "uri"
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "kind": {
            "$ref": "#/components/schemas/Kind"
          },
          "group": {
            "type": "string",
            "examples": [
              "Silicon Apps · Start"
            ]
          },
          "snippet": {
            "type": "string"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "query",
          "filters",
          "total",
          "limit",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "filters": {
            "type": "object",
            "properties": {
              "product": {
                "$ref": "#/components/schemas/Product"
              },
              "kind": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Kind"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "total": {
            "type": "integer",
            "description": "Every match, before the limit."
          },
          "limit": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        }
      },
      "PageSummary": {
        "type": "object",
        "required": [
          "path",
          "title",
          "description",
          "product",
          "kind",
          "type",
          "url",
          "markdown_url",
          "modified"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "The path after /docs/ (empty for the docs landing page).",
            "examples": [
              "apps/start/publish"
            ]
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "kind": {
            "$ref": "#/components/schemas/Kind"
          },
          "type": {
            "type": "string",
            "enum": [
              "Instructions",
              "Explanation",
              "Reference",
              "Overview"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdown_url": {
            "type": "string",
            "format": "uri"
          },
          "modified": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "PageList": {
        "type": "object",
        "required": [
          "filters",
          "total",
          "pages"
        ],
        "properties": {
          "filters": {
            "type": "object"
          },
          "total": {
            "type": "integer"
          },
          "pages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PageSummary"
            }
          }
        }
      },
      "PageLink": {
        "type": "object",
        "required": [
          "path",
          "title",
          "url"
        ],
        "properties": {
          "path": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "PageDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PageSummary"
          },
          {
            "type": "object",
            "required": [
              "headings",
              "related",
              "previous",
              "next",
              "markdown"
            ],
            "properties": {
              "headings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    },
                    "depth": {
                      "type": "integer"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              },
              "related": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PageLink"
                }
              },
              "previous": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PageLink"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "next": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PageLink"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "markdown": {
                "type": "string",
                "description": "The page's Markdown as written, after its front matter."
              }
            }
          }
        ]
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "method": {
            "type": "string",
            "examples": [
              "initialize",
              "tools/list",
              "tools/call"
            ]
          },
          "params": {
            "type": "object"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {}
            }
          }
        }
      }
    }
  }
}