Skip to the page

Using the API

AI agents

An AI agent can sign itself up, work in a sandbox of its own and hand its person a claim link; or ask a person who already has an account for a key that acts for them. Either way, an agent never does more than a person may.

For agents

The runbook written for you is rykloud.com/agent-signup.md; the same for machines is /.well-known/agent-access.json, and /llms.txt lists every route. All three are built from the API's own route table.

Sign up

A challenge is a short problem you answer by reading (a number in a noisy sentence, a word from a list, a fact from notes), plus a proof of work: a nonce such that sha256(prefix + nonce) starts with the asked number of zero bits. One answer per challenge. The mailed code is useless without the sign-up secret, and opening the mail's link spends nothing, so a mail scanner cannot use it up.

# 1. A challenge to read and a proof of work
curl -s -X POST https://api.rykloud.com/v1/agents/challenges -H 'content-type: application/json' -d '{"purpose": "signup"}'

# 2. Sign up (the answer, the nonce, a mailbox you can read, the terms)
curl -s -X POST https://api.rykloud.com/v1/agents/signups -H 'content-type: application/json' -d '{
  "challengeId": "<challengeId>", "answer": "<answer>", "nonce": "<nonce>",
  "email": "<mailbox>", "agent": {"name": "<a name your person knows>"},
  "acceptTerms": true, "termsVersion": "<terms.version>"}'
# keeps signupSecret (rksu_...), shown once

# 3. The 8 letter code from the mail, with the secret
curl -s -X POST https://api.rykloud.com/v1/agents/signups/<signupId>/verify \
  -H "authorization: Bearer $SIGNUP_SECRET" -H 'content-type: application/json' -d '{"code": "<CODE>"}'
# answers key.secret (rka_..., shown once), your sandbox organisation and claim.url

The sandbox, and the claim

Until a verified person claims it, an agent works in a sandbox organisation of its own: at most three keys, ten site previews a day, sixty requests a minute per key, and no environments, products, people, domains, billing or mail to anyone. Anything else answers 403 agent_unclaimed with how to get claimed. An unclaimed sandbox ends after 14 days.

Give your person claim.url. They open it signed in to their Rykon account, see who you are and what you did, and claim you: the sandbox becomes their organisation and your keys act for them, with the scope they chose. The usual rules then apply, one free trial per person among them.

Delegation: acting for a person who has an account

The device code flow (RFC 8628). Your person approves one screen at app.rykloud.com/app/agents/approve: the organisation, read or write (write needs an owner or admin), how many days (90 at most), a monthly spend cap (an owner's), and the addresses it may work from.

curl -s -X POST https://api.rykloud.com/v1/agents/challenges -d '{"purpose": "delegation"}' -H 'content-type: application/json'
curl -s -X POST https://api.rykloud.com/v1/agents/delegations -H 'content-type: application/json' -d '{
  "challengeId": "<challengeId>", "nonce": "<nonce>", "agent": {"name": "Release helper"},
  "request": {"scope": "write", "expiresInDays": 30, "spendCapUsd": 0}}'
# show your person verificationUriComplete; then every 5 seconds:
curl -s -X POST https://api.rykloud.com/v1/agents/delegations/token -H 'content-type: application/json' -d '{"deviceCode": "<rkd_...>"}'

Keys

rka_ and 43 characters, shown once, kept only as a hash. A key works in one organisation; another is not found. Rotate it with POST /v1/agents/me/keys/:id/rotate (the old secret works ten more minutes), revoke it, or make another that can do no more than the one making it. Your person sees every key on the organisation's Agents page with its last use, its use in 30 days and its record, and can shorten it, lower its cap, set addresses or revoke it.

export RYKLOUD_TOKEN=rka_...
curl -s https://api.rykloud.com/v1/agents/me -H "authorization: Bearer $RYKLOUD_TOKEN"
curl -s -X POST https://api.rykloud.com/v1/agents/me/sites/previews -H "authorization: Bearer $RYKLOUD_TOKEN" \
  -H 'content-type: application/json' -d '{"template": "atelier", "name": "Rosa Dental"}'
ClassMeansExamples
sandboxAn unclaimed agent tooWho am I, its organisation and checklist, site previews, status, prices
keyA claimed or delegated agent, within its scopeProjects, environments asked for, resources, logs, settings previewed
moneyWithin the key's monthly spend cap, else the personApproving a plan or a change at its stated price
personNever an agentPeople and roles, invitations, ownership, transfers, revealing secrets, deleting

Try without an account

GET https://rykloud.com/api/agents/demo/templates?q=dentist lists site templates with live demos; POST https://rykloud.com/api/agents/demo/ask with {"question": "..."} answers from the help centre and these guides. Both are limited per address.

Limits and errors

Generous for real use, strict on abuse: challenges and sign-ups per address, sign-ups per mailbox and per mail domain, three unclaimed agents per mailbox, wrong answers raising the proof of work and then pausing the address for an hour, throwaway mailboxes refused (disposable_email), and a ceiling across everyone (signup_busy). A 429 carries detail.retryAfterSeconds. See Errors.

MCP clients can use https://api.rykloud.com/v1/public/agents/mcp (streamable HTTP), whose tools are these same steps.