StackOne Connector API

The stackone.com connector catalogue is available as a public JSON API. It exists so an agent can read the catalogue without scraping HTML. Everything it returns is already published on the connector pages.

Machine-readable description: /openapi.json (OpenAPI 3.1). Discovery linkset: /.well-known/api-catalog (RFC 9727).

Endpoints

Base URL https://www.stackone.com. Successful reads are application/json and errors are RFC 9457 application/problem+json. CORS is open to any origin, and successful reads set Cache-Control: public, max-age=300, s-maxage=3600, so a client may cache them for five minutes.

Call these paths with their trailing slash. The unslashed form redirects, and a browser does not follow a redirect on a CORS preflight, so a cross-origin fetch() to /api/v1/connectors fails where /api/v1/connectors/ succeeds.

The connector list endpoint carries a pagination object (limit, offset, total, has_more) and a Link header with rel="next" and rel="prev" when more pages exist.

No authentication, no write API

There is no API key, no token, and no account. Every endpoint accepts GET, HEAD, and OPTIONS. Any other method on a documented endpoint returns 405 with an Allow header (a cross-site form-encoded write is rejected earlier, with a 403, by the site's CSRF protection), while a request of any method to a path that does not exist under /api/v1/ returns a 404 problem document. Nothing here writes data.

This is the website API. The StackOne product API is a separate, authenticated surface documented at docs.stackone.com. Its machine-readable specs live with the API itself: oas/stackone.json for the platform API, and one document per unified category such as oas/hris.json.

Versioning policy

The major version is part of the path. A breaking change ships as a new /api/vN prefix rather than changing the behaviour of an existing one. Removing or renaming a field, removing an endpoint, or tightening validation counts as breaking.

Additive changes land inside /api/v1 at any time: new fields, new optional query parameters, new endpoints, and new entries in the connector catalogue. Clients should ignore fields they do not recognise. The version in /openapi.json tracks those additions.

Error model

Every error is an RFC 9457 problem document served as application/problem+json. Alongside the standard members it always carries a stable code to branch on and a resolution describing the next step.

{
  "type": "https://www.stackone.com/docs/api/#connector-not-found",
  "title": "Connector not found",
  "status": 404,
  "detail": "No StackOne connector matches the slug \"foo\".",
  "instance": "https://www.stackone.com/api/v1/connectors/foo/",
  "code": "connector_not_found",
  "resolution": "List available connectors at https://www.stackone.com/api/v1/connectors/ and retry with a slug from that response.",
  "documentation_url": "https://www.stackone.com/docs/api/#errors"
}

Error codes

invalid_query_parameter

A query parameter is missing, malformed, or outside its allowed range.

connector_not_found

No connector in the StackOne catalogue matches the requested slug.

resource_not_found

The requested /api/v1 path does not exist.

method_not_allowed

The endpoint is read-only and the request used a method other than GET, HEAD, or OPTIONS.

missing_url_parameter

The required url query parameter was not supplied.

invalid_url

The supplied url query parameter is not a parsable absolute URL.

url_not_supported

The supplied url points at a host this endpoint does not serve metadata for.

unsupported_format

The requested response format is not implemented.

page_not_found

No published stackone.com page matches the supplied url.

Discovery

Every API response carries a Link header pointing at the OpenAPI document (rel="service-desc"), the API catalog (rel="api-catalog"), and this page (rel="service-doc"), so a client that lands on any endpoint can find the rest of the surface from the response alone.