Every request goes to the application host, not the developer-documentation
host. For Hodoflow Cloud the examples use https://hodoflow.com; a self-hosted
deployment substitutes its configured application origin.
export HODOFLOW_BASE_URL="https://hodoflow.com"
Keep the origin free of a trailing slash, then append one complete mount and
path. The public OpenAPI document advertises the application origin while each
operation already contains its full /api/... path.
Canonical mounts
| Surface | Canonical request |
|---|---|
| Token exchange | POST $HODOFLOW_BASE_URL/api/v1/oauth/token |
| JSON:API | $HODOFLOW_BASE_URL/api/json/v1/... |
| GraphQL | POST $HODOFLOW_BASE_URL/api/graphql |
| Webhook ingestion | POST $HODOFLOW_BASE_URL/api/v1/webhooks/$TRIGGER_TOKEN |
Legacy token and webhook paths containing an organization domain remain temporarily available for compatibility but are deprecated. New clients must use the canonical apex forms above.
Workspace context comes from the service account
A service account is created while one workspace is selected. That stored workspace, together with its organization and active run-as member, determines what API requests can see. Do not send a tenant, organization, or workspace ID as an authority override. A similarly named resource in another workspace is not visible through this credential.
Hodoflow validates the signed credential identity, then reloads the service account, workspace, scopes, and run-as membership for each request. Claims help locate the tenant record; the mutable database state remains authoritative.
Use separate service accounts when an integration needs separate workspace, scope, ownership, or revocation boundaries. Never reuse one credential merely to avoid another token exchange.
Versions are surface-specific
| Surface | Version identity | How it changes |
|---|---|---|
| JSON:API | v1 in the path and x-api-version response header |
Breaking changes require a new mount such as /api/json/v2 |
| GraphQL | Date version in x-api-version and the SDL header |
Additive evolution in place; removals follow GraphQL deprecation |
| Token exchange | /api/v1 route family |
OAuth response shape is versioned with the route |
| Webhook ingestion | /api/v1 route family |
Delivery response and authentication contract are versioned with the route |
Do not send a JSON:API version header to change GraphQL behavior. Do not infer a
GraphQL schema date from v1. Record the response's x-api-version and
x-request-id with integration diagnostics.
Discovery URLs
Use release-matched public artifacts rather than scraping HTML:
- OpenAPI JSON for HTTP operations and schemas;
- GraphQL SDL for GraphQL names and types;
- LLM index and full Markdown corpus for prose;
.mdon any guide URL for that page's canonical Markdown.
Continue with Authentication or read the full Versioning and changelog policy.