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”
  • Use read-only tokens for browsing / planning steps; only escalate to a write token when about to mutate.
  • Store tokens in OS keychain or equivalent, never in plain-text config.
  • Rotate after suspected exposure: DELETE /me/access_tokens/:id.json and mint a new one.
  • One token per agent / device — easier to revoke surgically.

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 Hypemarket support debug rate-limit issues for your agent specifically.

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 #9 ‘Spring Lipstick Drop’ in the brand ‘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, open an issue at github.com/yshmarov/hypemarket with the request, response, and your agent’s User-Agent.