API quick start | Hopya Docs

The Hopya REST API belongs to your application instance, not this public documentation site. Its base path is /api/v1. Read the complete API reference for endpoint payloads, permissions, limits, and errors.

Create a restricted client identity

Sign in to your instance → Account settings → Personal access tokens.
Create a recognizable token; raw value is revealed once.
Store it privately, never in URLs, source code, this site, or shared logs.

Create a restricted client identity: reference table
Client identity	Boundary
Dedicated account	Only required memberships/permissions
Token	Inherits current account permissions; no separate scopes
Access changes	Revocation, expiry, suspension, membership changes remain authoritative

The examples below assume HOPYA_URL and HOPYA_API_TOKEN were supplied privately. HOPYA_URL is the bare HTTPS origin of your instance. Do not paste a real token into a shell command or documentation example.

Discover accessible workspaces

curl --fail-with-body "$HOPYA_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $HOPYA_API_TOKEN"

Success responses are direct JSON objects/arrays, not a common nested data envelope. Get a workspace detail response to identify permitted hierarchy nodes and an actual list ID. Visibility of metadata does not grant permission to read task bodies or Table records.

Read tasks without truncating the dataset

curl --fail-with-body --get \
  "$HOPYA_URL/api/v1/workspaces/$WORKSPACE_ID/items/page" \
  -H "Authorization: Bearer $HOPYA_API_TOKEN" \
  --data-urlencode "limit=200"

Read tasks without truncating the dataset: reference table
Response / next step	Rule
`{items,nextCursor}`	Continue while cursor is non-null
Next request	Same workspace/filters, unchanged `cursor`
Short page	Not completion; encoded byte budget may reduce returned rows
Consistency	Current access rechecked per page; not one frozen cross-request snapshot

Use the complete bulk endpoint when one consistent snapshot is required. Treat an interrupted download as failure; never label a partially delivered export complete.

Review before creating a task

The create endpoint is POST /api/v1/workspaces/:wid/items. It needs a real list nodeId in that workspace and a title. A destination’s effective statuses govern accepted status IDs.

Prepare a task.json file, replacing the illustrative UUID with a list returned by your own instance:

{
  "nodeId": "11111111-1111-4111-8111-111111111111",
  "title": "Review the deployment backup plan"
}

Only run the following mutation after a human reviews the intended workspace, destination, and contents:

curl --fail-with-body \
  "$HOPYA_URL/api/v1/workspaces/$WORKSPACE_ID/items" \
  -H "Authorization: Bearer $HOPYA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @task.json

AI proposals and exposed MCP write tools are not approval for a mutation. Use the ordinary API permission boundary and require explicit human confirmation for AI-driven changes.

Preserve concurrent changes

Preserve concurrent changes: reference table
Write	Required care
Task PATCH	Read current task; exact `updatedAt` → `expectedUpdatedAt`; only intended fields
`customFields`	Complete replacement map; preserve unrelated entries
Stale revision	`409`, no change; refresh/reconcile and review changed intent before retry
Document/Table	Own required revision contracts in reference
Live Table	Value-hash revision, not invented ISO timestamp

Handle errors and uncertain writes

Handle errors and uncertain writes: reference table
Status	Client action
400 / 413	Correct the payload or reduce its size; do not retry unchanged
401	Refresh/recreate credentials only through the authorized account workflow
403 / 404	Check current workspace permissions and resource identity
409	Read the current version and reconcile the intended change
429	Respect `Retry-After` and reduce concurrency
502 / 503 / 504	Report sanitized context and investigate integration/deadline state

Do not automatically replay a non-idempotent mutation merely because the response was lost. A remote write may already have committed.

Machine-readable contracts and MCP

Your instance publishes its OpenAPI description at /api/v1/openapi.json. For tooling, use the specification served by the exact version you deployed; this site’s reference is pinned to v0.3.0 and does not proxy a live API or collect tokens.

For MCP stdio/SSE setup, read Optional integrations. Writes are disabled by default and tool exposure never substitutes for human approval.