# Hodoflow developer documentation > Choose the right API surface, complete a safe first request, and move from outcome-focused guides into exact machine contracts. Reference documentation for the Hodoflow HTTP API. Append `.md` to any page URL for its markdown source. ## Get started - [Build with Hodoflow](https://developer.hodoflow.com/index.md): Choose the right API surface, complete a safe first request, and move from outcome-focused guides into exact machine contracts. - [Make your first API request](https://developer.hodoflow.com/get-started/first-api-request.md): Create read-only service-account access, exchange it for a short-lived token, and verify a bounded workflow-list response. - [Choose an API surface](https://developer.hodoflow.com/get-started/choose-an-api.md): Match configuration, warehouse reads, and inbound event delivery to the correct Hodoflow API surface and prerequisites. - [Base URLs, workspaces, and versions](https://developer.hodoflow.com/get-started/base-urls-workspaces-versions.md): Build canonical Hodoflow API URLs and understand how service-account workspace context and surface-specific versions are selected. ## Authentication - [Authentication](https://developer.hodoflow.com/authentication.md): Create workspace-scoped service accounts, exchange client credentials, and operate short-lived bearer tokens with least privilege. - [Exchange service-account credentials](https://developer.hodoflow.com/authentication/token-exchange.md): Call the client-credentials token endpoint safely, interpret its response, and cache short-lived bearer tokens without a refresh token. - [Scopes and run-as permissions](https://developer.hodoflow.com/authentication/scopes-and-permissions.md): Apply Hodoflow's two-layer authorization model and choose the least-privilege scope for each API surface and operation. - [Rotate and revoke credentials](https://developer.hodoflow.com/authentication/rotation-and-revocation.md): Roll service-account secrets without downtime, promote the new pair, and revoke access with predictable runtime effect. ## Guides - [List and inspect workflows](https://developer.hodoflow.com/guides/list-workflows.md): Retrieve a bounded workflow collection, select one resource, and inspect its exact JSON:API attributes and response headers. - [Follow a workflow run](https://developer.hodoflow.com/guides/follow-workflow-run.md): Find a recent workflow run, retrieve its current state, and inspect safe per-step outcomes without exposing payloads. - [Perform an idempotent write](https://developer.hodoflow.com/guides/idempotent-write.md): Create one test dashboard through JSON:API, replay the identical request safely, and recognize a conflicting key reuse. ## API reference - [API reference](https://developer.hodoflow.com/reference): Browse the generated JSON:API operation reference. ## Platform behavior - [JSON:API documents and media types](https://developer.hodoflow.com/platform/json-api.md): Read and write Hodoflow's path-versioned JSON:API documents with the correct envelopes, headers, resource identities, and relationships. - [Pagination, filtering, sorting, and sparse fields](https://developer.hodoflow.com/platform/pagination-filtering-sorting.md): Bound JSON:API collections explicitly and combine operation-declared filters, sort fields, includes, and sparse fieldsets safely. - [Errors and request IDs](https://developer.hodoflow.com/platform/errors-request-ids.md): Distinguish JSON:API, GraphQL, token, and webhook failures; use stable codes, correlation IDs, and retryability without leaking credentials. - [Idempotency and retries](https://developer.hodoflow.com/platform/idempotency-retries.md): Retry Hodoflow operations safely by separating JSON:API response replay, webhook delivery deduplication, read retries, and permanent failures. - [Rate limits](https://developer.hodoflow.com/platform/rate-limits.md): Interpret configurable Hodoflow request windows, Retry-After responses, and the separate budgets for APIs and webhook ingestion. - [Versioning and changelog](https://developer.hodoflow.com/platform/versioning-changelog.md): Understand Hodoflow's surface-specific compatibility policy, response version headers, deprecation signals, and release-matched artifacts. ## GraphQL - [GraphQL warehouse API](https://developer.hodoflow.com/graphql.md): Use the read-only factQuery operation to retrieve latest or historical warehouse records for an existing data model. - [Run your first warehouse query](https://developer.hodoflow.com/graphql/first-query.md): Obtain a real data-model slug, send a bounded factQuery with variables, and verify empty or populated GraphQL results. - [factQuery arguments and results](https://developer.hodoflow.com/graphql/fact-query.md): Understand latest versus timeline semantics and every public factQuery argument, PageOfFact field, and Fact field. - [GraphQL filters, pagination, and limits](https://developer.hodoflow.com/graphql/filters-pagination-limits.md): Encode factQuery filters safely, page with explicit limits and offsets, and stay within time-window, complexity, depth, and token guards. ## Webhook ingestion - [Webhook ingestion](https://developer.hodoflow.com/webhook-ingestion.md): Send authenticated inbound deliveries to saved, active webhook workflows and follow the runs they create. - [Send your first webhook delivery](https://developer.hodoflow.com/webhook-ingestion/first-delivery.md): Configure an active webhook workflow, send one idempotent JSON delivery, and verify the accepted run through JSON:API. - [Webhook authentication and signatures](https://developer.hodoflow.com/webhook-ingestion/authentication-signatures.md): Combine the trigger URL, selected service-account bearer token, and optional API-key or raw-body HMAC verification safely. - [Webhook deduplication, retries, and troubleshooting](https://developer.hodoflow.com/webhook-ingestion/retries-troubleshooting.md): Choose stable delivery IDs, interpret accepted duplicates, and retry only transient webhook-ingestion failures. ## Tools and downloads - [Tools and downloads](https://developer.hodoflow.com/tools.md): Download the public OpenAPI and GraphQL contracts, browse the raw API viewer, or consume the Markdown and LLM indexes. - [OpenAPI contract](https://developer.hodoflow.com/tools/openapi.md): Download and use Hodoflow's release-matched HTTP contract for JSON:API, token exchange, and webhook ingestion. - [GraphQL SDL contract](https://developer.hodoflow.com/tools/graphql-sdl.md): Download Hodoflow's versioned GraphQL schema and use it for validation and type generation with the runtime rules kept in view. ## Specifications - [OpenAPI document](https://developer.hodoflow.com/openapi.json): Machine-readable description of every exposed JSON API path. - [GraphQL schema](https://developer.hodoflow.com/schema.graphql): SDL for the GraphQL transport. - [Product documentation](https://hodoflow.com/help): Help Center guides for the product these APIs drive. ## Optional - [Full documentation](https://developer.hodoflow.com/llms-full.txt): Every page on this site inlined as one markdown document.