{
  "openapi": "3.1.0",
  "info": {
    "title": "Finance Foundation API",
    "version": "1.0.0",
    "description": "The open data and intelligence layer for global finance. Open reference data — no auth, CORS enabled, seed-0.7 · marketcap-1 · 2026-08-30. Figures are approximate reference values, not real-time. Licensing: our compilation and schema are CC BY 4.0; fields sourced from a provider carry that provider's terms and are labelled with a source. See /api/v1/sources.",
    "contact": {
      "email": "admin@digitaldomains.market"
    }
  },
  "servers": [
    {
      "url": "https://finance.foundation"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "summary": "API index",
        "responses": {
          "200": {
            "description": "Endpoint list"
          }
        }
      }
    },
    "/api/v1/all": {
      "get": {
        "summary": "Entire dataset in one response (agent-friendly)",
        "responses": {
          "200": {
            "description": "All collections + schema"
          }
        }
      }
    },
    "/api/v1/schema": {
      "get": {
        "summary": "Finance Foundation Schema (entities and relationships)",
        "responses": {
          "200": {
            "description": "FF Schema"
          }
        }
      }
    },
    "/api/v1/indicators": {
      "get": {
        "summary": "Macro indicator definitions",
        "responses": {
          "200": {
            "description": "Indicator list"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search across all entity types",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Grouped results"
          },
          "400": {
            "description": "Missing q"
          }
        }
      }
    },
    "/api/v1/resolve": {
      "get": {
        "summary": "Resolve a ticker, LEI, ISIN, FIGI, MIC or name to entities",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked matches with identifiers and links"
          },
          "400": {
            "description": "Missing q"
          }
        }
      }
    },
    "/api/v1/ingest": {
      "post": {
        "summary": "Extract FF-Schema entities and relationships from unstructured financial text (LLM; 20/day per IP; read-only transform — output is not added to the dataset)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 6000
                  }
                },
                "required": [
                  "text"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "entities + relationships + unresolved_identifiers + warnings"
          },
          "422": {
            "description": "Extraction failed"
          },
          "429": {
            "description": "Daily limit"
          }
        }
      }
    },
    "/api/v1/live": {
      "get": {
        "summary": "Reference values (crypto, FX, rates, CPI) refreshed every 3 hours, with per-series source and observation dates — not real-time",
        "responses": {
          "200": {
            "description": "Latest observation per series"
          }
        }
      }
    },
    "/api/v1/graph/{type}/{id}": {
      "get": {
        "summary": "Knowledge-graph neighborhood of an entity",
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "companies",
                "markets",
                "assets",
                "funds",
                "banks",
                "countries",
                "research",
                "clearing"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "nodes + edges"
          },
          "404": {
            "description": "Unknown entity"
          }
        }
      }
    },
    "/api/v1/companies": {
      "get": {
        "summary": "List listed companies",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/companies/{id}": {
      "get": {
        "summary": "One of: listed companies",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/markets": {
      "get": {
        "summary": "List exchanges (mic codes)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/markets/{id}": {
      "get": {
        "summary": "One of: exchanges (mic codes)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/assets": {
      "get": {
        "summary": "List reference assets",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Crypto",
                "Commodity",
                "Index",
                "Bond",
                "Currency"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/assets/{id}": {
      "get": {
        "summary": "One of: reference assets",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/funds": {
      "get": {
        "summary": "List funds",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/funds/{id}": {
      "get": {
        "summary": "One of: funds",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/banks": {
      "get": {
        "summary": "List systemically important banks",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/banks/{id}": {
      "get": {
        "summary": "One of: systemically important banks",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/countries": {
      "get": {
        "summary": "List jurisdictions",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/countries/{id}": {
      "get": {
        "summary": "One of: jurisdictions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/research": {
      "get": {
        "summary": "List research briefs",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/research/{id}": {
      "get": {
        "summary": "One of: research briefs",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    },
    "/api/v1/clearing": {
      "get": {
        "summary": "List clearing houses and central securities depositories",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring filter"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_version": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "collection": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/clearing/{id}": {
      "get": {
        "summary": "One of: clearing houses and central securities depositories",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity envelope"
          },
          "404": {
            "description": "Unknown id"
          }
        }
      }
    }
  }
}