Build with Hodoflow

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. 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
• Observe: Follow a workflow run
• Write safely: Perform an idempotent write
• Reference: Browse JSON:API resources

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
• Learn: Filters, pagination, and limits
• Reference: Inspect factQuery

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
• Secure: Sender authentication and signatures
• Reference: Inspect the delivery endpoint

Read Choose an API surface for a detailed decision table and Base URLs, workspaces, and 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.

Contracts and tools

The curated API 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 — JSON:API plus reviewed token and webhook operations
• GraphQL SDL — the release-matched GraphQL schema
• Raw Swagger viewer — a secondary, non-executing OpenAPI viewer
• Markdown and LLM index — 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. For product setup, use the Help Center; for a traceable API failure, retain x-request-id and follow Errors and request IDs.