Skip to main content
When the data you need lives behind a system that isn’t natively supported, you can connect it as a generic HTTP API. Investigations call that API during an incident to pull in context unique to your stack — a deployment record, a feature flag state, the output of an internal service.
HTTP APIs are connected directly, with their own endpoint and credentials. There’s no provider route. See How telemetry works for how investigations decide when to reach for a connected source.

​
What we support

You describe your API with an OpenAPI specification, and investigations use that spec to construct requests against it: which paths exist, what each one does, the parameters it takes, and the shape of what it returns. During an investigation, a request is made to the endpoints that look relevant, and the response is read back as context.

​
Describe how to use the API, not just its shape

The OpenAPI spec tells investigations what your API can do. Custom guidance tells them when and why to use it — which endpoint answers which question, how to read a response, what a given field means for your incident. You provide this alongside the spec, and it’s used to steer how the API is queried. An endpoint that lists recent deploys is far more useful when the guidance says “use this to check whether a change shipped just before the incident started”.

​
Safe by construction

Investigations only ever read. Requests go out over HTTPS to the endpoint you configure, responses are capped in size so a large payload can’t overwhelm an investigation, and the host you supply is validated to keep requests pointed at the intended service. Point the connection at a read-only API, or scope the credential to read access, and there’s nothing an investigation can change.

​
Connecting an HTTP API

Connect your API directly with its endpoint, credentials, and a description of how to use it.
  1. From the Investigations settings, add a telemetry data source and choose HTTP API.
  2. Configure the connection:
    • Endpoint: the base URL of your API, without the https:// prefix. The connection is always made over HTTPS.
    • Authentication: a bearer token or basic auth (username and password). You can also add custom headers that are sent with every request.
    • OpenAPI spec: the specification describing your API’s paths, parameters, and responses.
    • Custom guidance (optional): a description of how investigations should use the API.
  3. Test the connection, then save it.
Once connected, the HTTP API is available to investigations straight away. You can disable it at any time if you’d prefer investigations didn’t call it.

​
Best practice

  • Point the connection at a read-only API, or use a credential scoped to read access. Investigations never need to write.
  • Keep the OpenAPI spec to the endpoints you want investigations to use. A smaller, focused spec leads to more accurate requests than a large one covering your whole surface.
  • Write custom guidance that says what each endpoint is for and how to read its response. This is the difference between an API investigations can call and one they call well.

Telemetry overview

How providers and data sources fit together.

How telemetry works

How investigations decide what to query and when.