Skip to content
Hypemarket API

Acting on behalf of users

This page is for AI agents (or developers building them) that operate the Hypemarket API on behalf of an authenticated human user.

Identity model

Section titled “Identity model”

Every request is authenticated by a personal access token the user generated. The agent is not a first-class principal in Hypemarket — it acts as the user.

That has two consequences:

  1. The agent inherits the user’s permissions. It cannot do anything the user couldn’t do in the web UI.
  2. The user is responsible. Audit logs attribute every action to the user, not the agent.

Both are deliberate. Treat the token with the same care as a password.

Token hygiene

Section titled “Token hygiene”
  • Pick the minimum scope at creation time — read if the agent only browses, write if it will create/update/delete. Scope is fixed for the life of the token; to change it, create a new one and revoke the old.
  • Store the token in the OS keychain (or equivalent), never in plain-text config or repo files.
  • One token per agent / device / environment — easier to revoke surgically.
  • After suspected exposure: DELETE /me/access_tokens/:id.json and mint a new one.

Picking the organization

Section titled “Picking the organization”

Most resources are nested under /organizations/:id. The first thing a fresh agent should do:

GET /organizations.json
Authorization: Bearer <token>
Accept: application/json

If the user belongs to a single org, auto-select it. If multiple, confirm with the user before mutating anything.

Section titled “Recommended request defaults”

Always send:

Authorization: Bearer <token>
Accept: application/json
User-Agent: <your-agent-name>/<version> (+contact-url)

A descriptive User-Agent helps debug issues affecting your agent specifically.

IDs are opaque strings

Section titled “IDs are opaque strings”

Every :id in URLs and JSON responses is a short opaque string (a sqid), not a sequential integer — for example gKpMxN, not 3. Treat them as opaque: don’t parse, increment, or try to guess them.

Idempotency

Section titled “Idempotency”

Hypemarket does not currently issue idempotency keys. To avoid duplicate writes:

  • PATCH is naturally idempotent for the same payload — safe to retry.
  • For POST (resource creation), record the response id locally before retrying. If the retry succeeds and you discover two records exist, DELETE the duplicate.
  • For destructive DELETE, treat 404 on retry as success.

Network errors and retries

Section titled “Network errors and retries”
  • 5xx or transport errors: exponential backoff, 3–5 attempts, jitter.
  • 429 is not currently emitted; rate limits surface as transient 503s under load.
  • 401 after a previously valid token usually means the user revoked it — stop and ask for a new token; do not retry.
  • 403: the user lacks the role for this action. Don’t retry — escalate to the user.

Confirmation patterns

Section titled “Confirmation patterns”

For irreversible operations (DELETE, publishing a campaign), echo back what you’re about to do using the values the API returned, not the values the user said:

“I’m about to delete the collab ‘Spring Lipstick Drop’ (gKpMxN) in the organization ‘Acme Cosmetics’. Confirm?”

This catches drift between user intent and selected resource (wrong org, stale id, etc.).

Reading docs programmatically

Section titled “Reading docs programmatically”

Every page on this site is also available as raw markdown:

  • Append .md to any URL: https://docs.hypemarket.ai/start/authentication.md
  • llms.txt — index of all pages, agent-friendly
  • llms-full.txt — entire docs concatenated, suitable for one-shot retrieval

When in doubt, fetch the live markdown rather than relying on training-set memory of this API — the resource shapes evolve.

Reporting issues

Section titled “Reporting issues”

If you hit ambiguous behavior or undocumented responses, email [email protected] with the request, response, and your agent’s User-Agent.