{
  "openapi": "3.1.0",
  "info": {
    "title": "The AI Record API",
    "version": "1.0.0",
    "summary": "Cited passages of what people at organizations have said about how they use AI.",
    "description": "A free API over The AI Record, an archive of what people at organizations have said about how they use AI, why, and with what results. No key, no quota, no sign-up, CORS open.\n\nEvery passage is returned verbatim with its source, an evidence grade (A filings and earnings calls, B the organization's own posts and talks, C interviews and press, D third-party estimates) and a verification status.\n\nRules for consumers:\n- Every passage is reproduced word for word from the cited source.\n- Check the verification status: \"reported\" means not yet confirmed by an independent second reader.\n- Organizations flagged aiVendor sell AI tools or services and have a reason to publish flattering numbers.\n- An empty result means the archive holds nothing on it, not that nobody has said anything.\n- Give the speaker, role, organization, date and source with every passage, and link the passage's own page (`url`).\n- Show a `context` note outside the quotation marks: it is the archive's note, not the speaker's words.\n\nAn MCP server with the same data is at https://the-ai-record.com/mcp (Streamable HTTP, no auth).",
    "license": {
      "name": "CC BY 4.0 for the archive's own grades, notes, topics and verification records; quotations remain the property of their rights holders",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://the-ai-record.com/api/v1"
    }
  ],
  "externalDocs": {
    "description": "Rules and every topic, organization and person, for language models",
    "url": "https://the-ai-record.com/llms.txt"
  },
  "paths": {
    "/search": {
      "get": {
        "operationId": "searchPassages",
        "summary": "Find passages on a subject, ranked.",
        "description": "Ranked keyword retrieval (BM25) over the archive, with checked passages and the clearest statements on a topic first. Returns verbatim passages with citations. `empty: true` means the archive holds nothing on point: say so rather than answering from memory. An empty `q` returns `needsQuery: true` and the topic directory.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "A question or subject in plain words.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 300
            },
            "example": "agents doing code review"
          },
          {
            "name": "org",
            "in": "query",
            "required": false,
            "description": "Only this organization (id or name).",
            "schema": {
              "type": "string"
            },
            "example": "stripe"
          },
          {
            "name": "person",
            "in": "query",
            "required": false,
            "description": "Only this speaker (id or name).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "Only this topic id (see /topics.json).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "grade",
            "in": "query",
            "required": false,
            "description": "Only these grades, comma separated.",
            "schema": {
              "type": "string"
            },
            "example": "A,B"
          },
          {
            "name": "verified",
            "in": "query",
            "required": false,
            "description": "true: only passages checked against the source.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked passages, possibly none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; see Retry-After."
          }
        }
      }
    },
    "/passages/{id}.json": {
      "get": {
        "operationId": "getPassage",
        "summary": "One passage.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The passage id, as in its page URL.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The passage.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/topics.json": {
      "get": {
        "operationId": "listTopics",
        "summary": "Every topic, with passage counts.",
        "responses": {
          "200": {
            "description": "Topics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/topics/{id}.json": {
      "get": {
        "operationId": "getTopic",
        "summary": "One topic and all its passages, clearest first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The topic id, as in its page URL.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The topic and its passages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/organizations.json": {
      "get": {
        "operationId": "listOrganizations",
        "summary": "Every organization, with passage counts and the AI-vendor flag.",
        "responses": {
          "200": {
            "description": "Organizations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/organizations/{id}.json": {
      "get": {
        "operationId": "getOrganization",
        "summary": "One organization: profile, size and results from its filings, its people, and its passages, strongest evidence first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The organization id, as in its page URL.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The organization.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/people.json": {
      "get": {
        "operationId": "listPeople",
        "summary": "Every person quoted or reporting, with role and organization.",
        "responses": {
          "200": {
            "description": "People.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/people/{id}.json": {
      "get": {
        "operationId": "getPerson",
        "summary": "One person: role, why their word counts, and their passages.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The person id, as in its page URL.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The person.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/misattributed.json": {
      "get": {
        "operationId": "listMisattributed",
        "summary": "Lines that circulate about an organization's AI use, checked: their words, close, out of context, or not theirs.",
        "responses": {
          "200": {
            "description": "Checked lines.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/stats.json": {
      "get": {
        "operationId": "getStats",
        "summary": "How big the archive is and how much is checked.",
        "responses": {
          "200": {
            "description": "Counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/search-index.json": {
      "get": {
        "operationId": "getSearchIndex",
        "summary": "The whole browser search index (large). Prefer /search.",
        "responses": {
          "200": {
            "description": "Every passage, for client-side search.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Passage": {
        "type": "object",
        "required": [
          "id",
          "text",
          "organization",
          "work",
          "grade",
          "verification",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string",
            "description": "Verbatim. Quote exactly."
          },
          "context": {
            "type": [
              "string",
              "null"
            ],
            "description": "The archive's note on the occasion. Not the speaker's words."
          },
          "speaker": {
            "type": [
              "string",
              "null"
            ]
          },
          "speakerUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "speakerLevel": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "executive",
              "leader",
              "practitioner",
              "outside",
              null
            ]
          },
          "role": {
            "type": [
              "string",
              "null"
            ]
          },
          "organization": {
            "type": "string"
          },
          "organizationUrl": {
            "type": "string"
          },
          "aiVendor": {
            "type": "boolean",
            "description": "The organization sells AI tools or services."
          },
          "work": {
            "type": "object",
            "description": "The source: title, type, date, publisher, locator, url."
          },
          "grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D"
            ]
          },
          "gradeMeaning": {
            "type": "string"
          },
          "verification": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "verified",
                  "reported"
                ]
              },
              "meaning": {
                "type": "string"
              },
              "reviewedOn": {
                "type": "string"
              }
            }
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "figures": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Numbers stated in the passage."
          },
          "url": {
            "type": "string",
            "description": "The passage's own page. Link this."
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "empty": {
            "type": "boolean",
            "description": "The archive holds nothing on point."
          },
          "needsQuery": {
            "type": "boolean"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Passage"
            }
          },
          "topic": {
            "type": [
              "object",
              "null"
            ],
            "description": "The topic page that best matches, when one clearly does."
          },
          "notice": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}