# Build with Hodoflow

> Choose the right API surface, complete a safe first request, and move from outcome-focused guides into exact machine contracts.

Hodoflow exposes three developer surfaces for three different jobs. Start with
the outcome you need, not with a transport name. Every authenticated surface
uses a workspace-scoped service account and short-lived bearer token, but their
prerequisites, versions, limits, and response shapes remain distinct.

## Start with a verified success

New to the API? [Make your first API request](/get-started/first-api-request).
That guide creates least-privilege `api_read` access, exchanges credentials, and
lists at most ten workflows. It succeeds even when the workspace has no data:
`200 OK` with `data: []` is the expected empty result.

The guide shows every request, representative response, checkpoint, recovery
step, and cleanup action. You need owner or admin access for service-account
setup, an active run-as member, Bash, cURL, and `jq`.

## Choose an outcome

### Manage configuration or observe work

Use **JSON:API** under `/api/json/v1` to inspect or manage workflows, workflow
runs, data models, dashboards, integrations, users, organizations, memberships,
and service-account metadata.

- Start: [List and inspect workflows](/guides/list-workflows)
- Observe: [Follow a workflow run](/guides/follow-workflow-run)
- Write safely: [Perform an idempotent write](/guides/idempotent-write)
- Reference: [Browse JSON:API resources](/reference/json-api/workflows)

### Query warehouse records

Use **GraphQL** at `POST /api/graphql` for the read-only `factQuery` operation.
You need an existing data model slug and warehouse records, so this is not the
empty-workspace quickstart.

- Start: [Run your first warehouse query](/graphql/first-query)
- Learn: [Filters, pagination, and limits](/graphql/filters-pagination-limits)
- Reference: [Inspect factQuery](/reference/graphql/fact-query)

### Send an event into a workflow

Use **webhook ingestion** at `POST /api/v1/webhooks/:token`. First create, save,
and activate a webhook workflow, then authenticate with the exact service
account selected on its trigger and the `webhooks` scope.

- Start: [Send your first delivery](/webhook-ingestion/first-delivery)
- Secure: [Sender authentication and signatures](/webhook-ingestion/authentication-signatures)
- Reference: [Inspect the delivery endpoint](/reference/webhooks/ingest)

Read [Choose an API surface](/get-started/choose-an-api) for a detailed decision
table and [Base URLs, workspaces, and versions](/get-started/base-urls-workspaces-versions)
before deploying an integration.

## Authentication in one minute

An owner or admin creates a service account in the intended workspace, chooses
an active run-as member, and grants only the scopes the integration needs. The
client ID and secret are exchanged at `POST /api/v1/oauth/token` for a bearer
token. The default lifetime is 900 seconds, but clients must trust the returned
`expires_in` value. No refresh token is issued.

On every API request Hodoflow reloads and validates the service account, its
scopes, workspace, and run-as membership. Deactivation, revocation, membership
changes, and scope removal therefore take effect without waiting for an already
minted token to expire. Continue with [Authentication](/authentication).

## Contracts and tools

The [curated API reference](/reference) is generated from the same enriched
contract as the machine artifacts. It shows exact operation scopes, parameters,
objects, examples, success semantics, stable errors, and retry behavior. Its
request builder changes copyable text only; it never sends a request or stores a
credential.

- [OpenAPI JSON](/openapi.json) — JSON:API plus reviewed token and webhook operations
- [GraphQL SDL](/schema.graphql) — the release-matched GraphQL schema
- [Raw Swagger viewer](/tools/swagger) — a secondary, non-executing OpenAPI viewer
- [Markdown and LLM index](/llms.txt) — every guide and machine surface
- Append `.md` to any guide URL for its canonical Markdown representation

Version and compatibility policy lives in [Versioning and changelog](/platform/versioning-changelog).
For product setup, use the [Help Center](/help); for a traceable API failure,
retain `x-request-id` and follow [Errors and request IDs](/platform/errors-request-ids).