{
  "openapi": "3.1.0",
  "info": {
    "title": "Decision Insights Public API",
    "version": "1.0.0",
    "summary": "Read the Decision Insights knowledge graph of companies, open source projects, published content and glossary terms.",
    "description": "The read endpoints answer an anonymous caller at the lowest rate-limit tier; signing in over OAuth raises the allowance and is the only way to reach the endpoints that act on your own account. Human documentation lives at https://decisioninsights.ai/developers/."
  },
  "servers": [
    {
      "url": "https://api.decisioninsights.ai/api/public/v1",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer documentation",
    "url": "https://decisioninsights.ai/developers/"
  },
  "x-service-info": {
    "categories": [
      "market-intelligence",
      "company-data",
      "technology-research",
      "knowledge-graph"
    ],
    "docs": {
      "apiReference": "https://decisioninsights.ai/developers/",
      "homepage": "https://decisioninsights.ai",
      "llms": "https://decisioninsights.ai/llms.txt"
    }
  },
  "security": [
    {},
    { "oauthBearer": [] },
    { "apiKeyHeader": [] }
  ],
  "tags": [
    { "name": "companies", "description": "Company lookup and profiles." },
    { "name": "projects", "description": "Open source projects." },
    { "name": "content", "description": "Published content." },
    { "name": "glossary", "description": "Technology glossary terms." },
    { "name": "search", "description": "Search every record type at once." },
    { "name": "watch-lists", "description": "Follow a set of companies. Requires an access token." },
    { "name": "webhooks", "description": "Be notified rather than poll. Requires an access token." }
  ],
  "paths": {
    "/companies": {
      "get": {
        "tags": ["companies"],
        "operationId": "lookupCompany",
        "summary": "Look up one company by its own domain",
        "description": "A lookup, not a listing: supply the company's domain (or website). When you have a keyword rather than a domain, use /search.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "The company's own domain, e.g. cisco.com. Either this or `website` is required.",
            "schema": { "type": "string" },
            "example": "cisco.com"
          },
          {
            "name": "website",
            "in": "query",
            "required": false,
            "description": "The company's website URL. Accepted in place of `domain`.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching company.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Company" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/companies/{uuid}": {
      "get": {
        "tags": ["companies"],
        "operationId": "getCompany",
        "summary": "Get one company profile",
        "parameters": [{ "$ref": "#/components/parameters/Uuid" }],
        "responses": {
          "200": {
            "description": "The company profile, with the themes and topics its content covers and its most recent content.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyProfile" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/projects": {
      "get": {
        "tags": ["projects"],
        "operationId": "searchProjects",
        "summary": "Search open source projects",
        "parameters": [{ "$ref": "#/components/parameters/Query" }],
        "responses": {
          "200": {
            "description": "Matching projects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "count": { "type": "integer" },
                    "projects": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ProjectSummary" }
                    }
                  },
                  "required": ["query", "count", "projects"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/projects/{uuid}": {
      "get": {
        "tags": ["projects"],
        "operationId": "getProject",
        "summary": "Get one open source project",
        "parameters": [{ "$ref": "#/components/parameters/Uuid" }],
        "responses": {
          "200": {
            "description": "The project, its owning organization, the companies appearing in its content, and its most recent linked content.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Project" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/content": {
      "get": {
        "tags": ["content"],
        "operationId": "searchContent",
        "summary": "Search published content",
        "parameters": [{ "$ref": "#/components/parameters/Query" }],
        "responses": {
          "200": {
            "description": "Matching content.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "count": { "type": "integer" },
                    "content": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ContentSummary" }
                    }
                  },
                  "required": ["query", "count", "content"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/content/{uuid}": {
      "get": {
        "tags": ["content"],
        "operationId": "getContent",
        "summary": "Get one published item",
        "parameters": [{ "$ref": "#/components/parameters/Uuid" }],
        "responses": {
          "200": {
            "description": "The item, with its canonical link, the link back to the original source, and its provenance.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Content" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/glossary": {
      "get": {
        "tags": ["glossary"],
        "operationId": "searchGlossary",
        "summary": "Search glossary terms",
        "parameters": [{ "$ref": "#/components/parameters/Query" }],
        "responses": {
          "200": {
            "description": "Matching glossary terms.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "count": { "type": "integer" },
                    "tags": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/GlossaryTerm" }
                    }
                  },
                  "required": ["query", "count", "tags"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/glossary/{uuid}": {
      "get": {
        "tags": ["glossary"],
        "operationId": "getGlossaryTerm",
        "summary": "Get one glossary term",
        "parameters": [{ "$ref": "#/components/parameters/Uuid" }],
        "responses": {
          "200": {
            "description": "The term, how much content carries it, and the companies most associated with it.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GlossaryTermDetail" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/search": {
      "get": {
        "tags": ["search"],
        "operationId": "search",
        "summary": "Search companies, projects, content and glossary terms at once",
        "parameters": [{ "$ref": "#/components/parameters/Query" }],
        "responses": {
          "200": {
            "description": "Matches grouped by record type.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "companies": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CompanySummary" }
                    },
                    "projects": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ProjectSummary" }
                    },
                    "content": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ContentSummary" }
                    },
                    "tags": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/GlossaryTerm" }
                    }
                  },
                  "required": ["query", "companies", "projects", "content", "tags"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/watch-lists": {
      "get": {
        "tags": ["watch-lists"],
        "operationId": "listWatchLists",
        "summary": "List your watch lists",
        "security": [{ "oauthBearer": [] }, { "apiKeyHeader": [] }],
        "parameters": [{ "$ref": "#/components/parameters/OrganizationUuid" }],
        "responses": {
          "200": { "$ref": "#/components/responses/AccountResource" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/AmbiguousOrganization" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["watch-lists"],
        "operationId": "createWatchList",
        "summary": "Create a watch list",
        "security": [{ "oauthBearer": [] }, { "apiKeyHeader": [] }],
        "parameters": [{ "$ref": "#/components/parameters/OrganizationUuid" }],
        "requestBody": { "$ref": "#/components/requestBodies/AccountResource" },
        "responses": {
          "200": { "$ref": "#/components/responses/AccountResource" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/AmbiguousOrganization" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/watch-lists/{id}/members": {
      "get": {
        "tags": ["watch-lists"],
        "operationId": "listWatchListMembers",
        "summary": "List the companies on a watch list",
        "security": [{ "oauthBearer": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/WatchListId" },
          { "$ref": "#/components/parameters/OrganizationUuid" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/AccountResource" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/AmbiguousOrganization" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["watch-lists"],
        "operationId": "addWatchListMember",
        "summary": "Add a company to a watch list",
        "security": [{ "oauthBearer": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/WatchListId" },
          { "$ref": "#/components/parameters/OrganizationUuid" }
        ],
        "requestBody": { "$ref": "#/components/requestBodies/AccountResource" },
        "responses": {
          "200": { "$ref": "#/components/responses/AccountResource" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/AmbiguousOrganization" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/watch-lists/{id}/members/{member_id}": {
      "delete": {
        "tags": ["watch-lists"],
        "operationId": "removeWatchListMember",
        "summary": "Remove a company from a watch list",
        "security": [{ "oauthBearer": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/WatchListId" },
          {
            "name": "member_id",
            "in": "path",
            "required": true,
            "description": "Identifier of the watch list member to remove.",
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/OrganizationUuid" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/AccountResource" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/AmbiguousOrganization" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/webhooks": {
      "post": {
        "tags": ["webhooks"],
        "operationId": "createWebhook",
        "summary": "Register a webhook",
        "description": "Webhooks let you be notified rather than poll. There is no GET on this path.",
        "security": [{ "oauthBearer": [] }, { "apiKeyHeader": [] }],
        "parameters": [{ "$ref": "#/components/parameters/OrganizationUuid" }],
        "requestBody": { "$ref": "#/components/requestBodies/AccountResource" },
        "responses": {
          "200": { "$ref": "#/components/responses/AccountResource" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/AmbiguousOrganization" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauthBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An OAuth access token issued by https://my.decisioninsights.ai. There is no API key to request. Register a client with RFC 7591 dynamic client registration at https://my.decisioninsights.ai/oauth2/register; a self-registered client is always an authorization_code client scoped to `profile`, whatever it asked for, so read the grant_types in the registration response. Only PKCE S256 is accepted and redirect URIs are matched exactly."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "The same OAuth access token, sent on its own for clients that send this header instead of Authorization."
      }
    },
    "parameters": {
      "Uuid": {
        "name": "uuid",
        "in": "path",
        "required": true,
        "description": "UUID of the record.",
        "schema": { "type": "string", "format": "uuid" }
      },
      "WatchListId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Identifier of the watch list.",
        "schema": { "type": "string" }
      },
      "Query": {
        "name": "q",
        "in": "query",
        "required": true,
        "description": "Search term. A request without it returns 400 naming the missing parameter.",
        "schema": { "type": "string", "minLength": 1 },
        "example": "observability"
      },
      "OrganizationUuid": {
        "name": "organizationUuid",
        "in": "query",
        "required": false,
        "description": "Which of your organizations to act as, when your account reaches more than one. A request that leaves it ambiguous returns 403 listing the organizations you can choose from.",
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "requestBodies": {
      "AccountResource": {
        "required": true,
        "description": "See https://decisioninsights.ai/developers/ for the fields this endpoint accepts.",
        "content": {
          "application/json": {
            "schema": { "type": "object" }
          }
        }
      }
    },
    "responses": {
      "AccountResource": {
        "description": "The resource, as JSON.",
        "content": {
          "application/json": {
            "schema": { "type": "object" }
          }
        }
      },
      "BadRequest": {
        "description": "A required parameter is missing or a value failed validation.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "invalid_request", "message": "q is required" }
          }
        }
      },
      "Unauthorized": {
        "description": "This endpoint acts on your own account and needs an access token.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": "unauthorized",
              "message": "A Bearer access token is required for this endpoint"
            }
          }
        }
      },
      "AmbiguousOrganization": {
        "description": "Your account reaches more than one organization and the request did not say which. The body lists the organizations you can choose from; repeat the request with ?organizationUuid=.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "No such record.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Over the rate limit for your tier. Wait the number of seconds in Retry-After rather than retrying immediately.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": { "type": "integer" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every failure answers with this shape.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable error code, e.g. invalid_request or unauthorized."
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of what went wrong."
          }
        },
        "required": ["error", "message"]
      },
      "CompanySummary": {
        "type": "object",
        "description": "A company as it appears in search results, ranked by how much content covers it.",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "website": { "type": "string" },
          "description": { "type": "string" },
          "content_volume": {
            "type": "integer",
            "description": "How much published content covers this company."
          }
        },
        "required": ["uuid", "name"]
      },
      "Company": {
        "type": "object",
        "description": "A company as returned by a domain lookup.",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "legal_name": { "type": "string" },
          "website": { "type": "string" },
          "description": { "type": "string" }
        },
        "required": ["uuid", "name"]
      },
      "CompanyProfile": {
        "type": "object",
        "description": "One company's full profile.",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "legal_name": { "type": "string" },
          "website": { "type": "string" },
          "description": { "type": "string" },
          "type": { "type": "string" },
          "employees": { "type": ["integer", "null"] },
          "location": { "type": ["string", "null"] },
          "linkedin": { "type": ["string", "null"] },
          "twitter": { "type": ["string", "null"] },
          "content_volume": { "type": "integer" },
          "themes": { "type": "array", "items": { "type": "object" } },
          "topics": { "type": "array", "items": { "type": "object" } },
          "recent_content": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ContentSummary" }
          }
        },
        "required": ["uuid", "name"]
      },
      "ProjectSummary": {
        "type": "object",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "type": { "type": "string" },
          "excerpt": { "type": "string" },
          "organization": { "type": ["object", "null"] },
          "content_volume": { "type": "integer" }
        },
        "required": ["uuid", "name"]
      },
      "Project": {
        "type": "object",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "type": { "type": "string" },
          "description": { "type": "string" },
          "website": { "type": ["string", "null"] },
          "owner_organization": { "type": ["object", "null"] },
          "content_volume": { "type": "integer" },
          "related_companies": { "type": "array", "items": { "type": "object" } },
          "recent_content": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ContentSummary" }
          },
          "truncated": {
            "type": "boolean",
            "description": "Whether the lists above were cut short for your tier."
          },
          "withheld": {
            "type": "integer",
            "description": "How many records were withheld at your tier."
          },
          "upgrade": { "type": ["string", "null"] }
        },
        "required": ["uuid", "name"]
      },
      "ContentSummary": {
        "type": "object",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "excerpt": { "type": "string" },
          "url": {
            "type": "string",
            "description": "Canonical link on Decision Insights."
          },
          "original_url": {
            "type": ["string", "null"],
            "description": "Link back to the original source."
          },
          "source": { "type": ["string", "null"] },
          "source_content_type": { "type": ["string", "null"] },
          "published_at": { "type": ["string", "null"], "format": "date-time" },
          "subject_company": { "type": ["object", "null"] },
          "tags": { "type": "array", "items": { "type": "object" } }
        },
        "required": ["uuid", "title"]
      },
      "Content": {
        "type": "object",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "canonical_url": { "type": "string" },
          "original_url": { "type": ["string", "null"] },
          "provenance": {
            "type": ["object", "null"],
            "description": "Where the item came from: source, brand and type."
          },
          "published_at": { "type": ["string", "null"], "format": "date-time" },
          "subject_company": { "type": ["object", "null"] },
          "tags": { "type": "array", "items": { "type": "object" } },
          "projects": { "type": "array", "items": { "type": "object" } }
        },
        "required": ["uuid", "title"]
      },
      "GlossaryTerm": {
        "type": "object",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "type": { "type": "string" },
          "abbreviation": { "type": ["string", "null"] },
          "definition": { "type": "string" }
        },
        "required": ["uuid", "name"]
      },
      "GlossaryTermDetail": {
        "type": "object",
        "properties": {
          "uuid": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "type": { "type": "string" },
          "abbreviation": { "type": ["string", "null"] },
          "definition": { "type": "string" },
          "content_volume": { "type": "integer" },
          "top_companies": { "type": "array", "items": { "type": "object" } },
          "truncated": { "type": "boolean" },
          "withheld": { "type": "integer" }
        },
        "required": ["uuid", "name"]
      }
    }
  }
}