Hodoflow / Developers
Sign in
Browse documentation
Help Center →
Concept All API surfaces

Choose an API surface

Match configuration, warehouse reads, and inbound event delivery to the correct Hodoflow API surface and prerequisites.

View as Markdown

Hodoflow has related API surfaces, not one interchangeable API. Choose by the job your integration performs. Authentication is shared; versioning, media types, pagination, errors, and prerequisites are not.

Decision table

Goal Surface Mount Prerequisite Scope
List or manage workflows, dashboards, data models, integrations, accounts, and runs JSON:API /api/json/v1 Service account in the target workspace api_read or api_write by method
Read latest or historical warehouse records GraphQL /api/graphql Existing data model slug and warehouse records api_read for factQuery
Send an inbound delivery into an active workflow Webhook ingestion /api/v1/webhooks/:token Saved, active webhook workflow and selected service account webhooks
Let an AI assistant read and author across your organizations MCP /api/mcp Personal access token minted on your profile No scopes; whatever your own memberships allow
Obtain a bearer token Token exchange /api/v1/oauth/token Active service-account client credentials No bearer scope; the resulting token carries configured scopes

If you are still unsure, start with JSON:API. A bounded workflow list is read-only and succeeds in an empty workspace, making it the deterministic way to verify the host, credential, workspace, scope, and response headers.

JSON:API for configuration and observability

JSON:API exposes reviewed resource operations under a path-versioned v1 mount. Collection requests can filter, sort, select sparse fields, include relationships, and paginate where the individual operation declares support. Always send Accept: application/vnd.api+json; writes also send that media type as Content-Type and should carry an Idempotency-Key.

Do not query warehouse fact rows through JSON:API. Use GraphQL for that logical table view. Begin with List and inspect workflows or browse the JSON:API reference.

GraphQL for warehouse reads

GraphQL exposes health and one authenticated data operation, factQuery. There are no public mutations or subscription fields. factQuery resolves a data model by slug, returns one latest row per entity or a bounded timeline, and uses offset pagination. Its default limit is 50, maximum is 250, and complexity usually imposes a smaller useful page size.

A new workspace cannot complete this path until it has a data model and facts. Follow Run your first warehouse query, which shows how to obtain the slug through JSON:API before querying.

MCP for AI assistants

MCP is the only surface authenticated by a personal access token rather than a service account, and the only one whose credential carries no scopes: it reaches every organization its owner is an active member of and does whatever its owner can do there. An assistant calls tools to list organizations, read records, inspect workflow runs, and search the documentation, and to author — create data models, save and activate workflows, build dashboards. Nothing on the surface deletes, publishes, or administers. Start at Connect an AI assistant.

Webhook ingestion for inbound events

Webhook ingestion is not an outbound event-subscription product. A sender posts JSON to the opaque trigger path shown by an active webhook workflow. The request must use the exact service account selected on that trigger, with the webhooks scope. A stable delivery key prevents duplicate workflow runs during the seven-day retention window.

The 202 response means the delivery was accepted and a run was enqueued; it does not mean the workflow completed. Continue by retrieving the returned run through JSON:API or opening Monitor. Start with Send your first delivery.

Do not blend the contracts

  • JSON:API's v1 path and x-api-version: v1 do not select a GraphQL schema version.
  • GraphQL field errors use a GraphQL errors array; JSON:API plug and resource errors use an errors document.
  • JSON:API idempotency replay applies to unsafe JSON:API requests, not to read-only factQuery.
  • Webhook delivery deduplication is a separate seven-day contract.
  • Only GraphQL uses query complexity, nesting-depth, and token-count limits.

Next, configure Base URLs, workspaces, and versions or complete the first API request.

Related documentation