Overview

Each inndx service exposes its own HTTP API. The orchestrator owns crawl configuration and state, the fetcher retrieves content, the parser turns content into results and manages extraction configuration, and the analytics service exposes recorded run and configuration history.

This section documents every endpoint, its parameters, and its request and response shapes. The conventions below are shared across all services and are referenced from each resource page rather than repeated.

Most users operate a deployment through crawlctl or the dashboard rather than calling these endpoints directly; this section documents the API underneath both.

Base URL and versioning

Every endpoint is served under the /v1 path prefix on the service's configured host and port. The default port is 8022. For a service reachable at http://localhost:8022, the jobs collection is at http://localhost:8022/v1/jobs.

All request and response bodies are JSON. Binary payloads (page bodies, screenshots, blob content) are base64 encoded inside JSON fields, except for the artifact blob download, which returns raw bytes.

Live reference

Every running service also serves an interactive reference at /.well-known/docs and the raw OpenAPI schema at /.well-known/openapi.json, generated from the running build. Use this written reference as the source of truth, and the live schema when you need to confirm the exact behavior of a specific deployment.

Authentication and tenancy

The services provide no built-in authentication of their own.

Pagination

List endpoints are cursor paginated. They accept the following query parameters and return results wrapped in a pagination envelope.

Each list endpoint accepts additional filter parameters, documented on its own page.

Query Parameters

Query parameters that accept multiple values (for example, include_ids) can be passed as repeated parameters with the bracket syntax (include_ids[]=id1&include_ids[]=id2). When the parameters take a nested object (for example, labels), use bracket syntax to express the nesting (labels[group]=job_sites&labels[env]=production).

It is recommended to use form url encoding instead of percent encoding when constructing URLs to ensure proper encoding of the brackets and other special characters, for example:

?param[]=Some+text+value&param[]=Another+value

Status codes

Error shapes

Errors return one of two JSON shapes. The HTTP status is the numeric code divided by 1000 (for example 404000 maps to 404, 422001 maps to 422, 500000 maps to 500). The trailing digits distinguish error variants that share a status.

{
  "code": 500000,
  "message": "A description of what went wrong.",
  "metadata": null
}

The metadata field is always present and is null unless structured context is available. The generic shape covers 400, 403, 404, 409, 500, and 502, along with a request body that cannot be processed (422000).

{
  "code": 422001,
  "fields": [
    {
      "field": "name",
      "errors": [
        { "code": "length", "message": null, "params": { "min": 1, "max": 255, "value": "" } }
      ]
    }
  ]
}

The validation shape is returned with code 422001 when one or more fields fail validation. Each entry in fields names a request field that failed and lists one or more errors against it. Each error carries a code (such as length or range), a message that is null unless the validator set one, and a params object that is present only when the validator supplied parameters.