{
  "openapi": "3.1.0",
  "info": {
    "title": "Lode API",
    "version": "1",
    "description": "Verified, source-linked facts about tools that integrate with business and developer platforms, with change history and vendor entities. Anonymous use is allowed at a low daily limit. Cite Lode and link the url for each fact. Commercial and bulk use needs a licence: https://trylode.io/data-access/",
    "contact": {
      "email": "data@trylode.io"
    }
  },
  "servers": [
    {
      "url": "https://trylode.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Integration": {
        "$ref": "https://trylode.io/schema/integration.schema.json",
        "description": "Integration record plus url, facts, vendor, cite_as and archived source links"
      },
      "Vendor": {
        "$ref": "https://trylode.io/schema/vendor.schema.json"
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "record_id",
          "type",
          "observed_at",
          "cause"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "app": {
            "type": "string"
          },
          "ecosystem": {
            "type": "string"
          },
          "type": {
            "enum": [
              "record.added",
              "record.removed",
              "fact.added",
              "fact.removed",
              "fact.changed"
            ]
          },
          "topic": {
            "type": "string"
          },
          "path": {
            "type": "string",
            "description": "Stable fact path, e.g. pricing.plan[Pro].price.USD"
          },
          "old": {},
          "new": {},
          "src": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cause": {
            "enum": [
              "new-coverage",
              "lode-update",
              "source-change-likely"
            ]
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "summary": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {},
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/v1/integrations": {
      "get": {
        "summary": "Find integrations for a buyer profile",
        "description": "Filters by required capabilities and region, then ranks by fit per the Lode ranking policy. Apps missing a requirement are excluded, not scored down.",
        "parameters": [
          {
            "name": "ecosystem",
            "in": "query",
            "required": true,
            "description": "Ecosystem slug, e.g. xero or vercel",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "AU, NZ, UK, US or CA",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "needs",
            "in": "query",
            "required": false,
            "description": "Comma-separated capability slugs from the ecosystem vocabulary",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results (50)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked key"
          },
          "429": {
            "description": "Daily quota reached"
          }
        }
      }
    },
    "/v1/integrations/{id}": {
      "get": {
        "summary": "One integration record",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "{app}--{ecosystem}, e.g. stripe--xero"
          }
        ],
        "responses": {
          "200": {
            "description": "Integration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Integration"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Daily quota reached"
          }
        }
      }
    },
    "/v1/vendors/{id}": {
      "get": {
        "summary": "One vendor across ecosystems",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Vendor id or domain"
          }
        ],
        "responses": {
          "200": {
            "description": "Vendor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Vendor"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Daily quota reached"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "Change events, newest first",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO date",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ecosystem",
            "in": "query",
            "required": false,
            "description": "Ecosystem slug",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Integration id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_new_coverage",
            "in": "query",
            "required": false,
            "description": "true to include record.added events",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max events (500)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked key"
          },
          "429": {
            "description": "Daily quota reached"
          }
        }
      }
    },
    "/v1/export": {
      "get": {
        "summary": "Full dataset as JSON Lines (commercial licence)",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "\"events\" to append the change log",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON Lines: one meta line, then integration, vendor and (optionally) event lines",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked key"
          },
          "403": {
            "description": "Licence required"
          },
          "429": {
            "description": "Daily quota reached"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "summary": "Requests used today by this key",
        "responses": {
          "200": {
            "description": "Usage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Key required"
          }
        }
      }
    }
  }
}