Sharing

Endpoints for letting people outside your workspace talk to a published agent. See Share an Agent for Testing for how the two modes differ. All endpoints here need a secret API key or a Studio session; publishable keys get 403.

Testers

Email invites, one per person. Each tester gets a free-minute allowance billed to your workspace.

List Testers

GET/v1/agents/:id/testers

Returns the agent's invites, the public link (link, or null), whether the deployment has share links on (link_feature), and agent_uses_owner_keys. When that last field is true, every tester needs at least 1 free minute.

Invite a Tester

POST/v1/agents/:id/testers

Field	Type	Required	Default	Description
email	string	Yes	-	The tester signs in with this address
minutes_limit	integer	No	0	Free minutes, 0 to 600. 0 means the tester pays from the start
expires_at	ISO date	No	null	When the invite stops working. Must be in the future

curl -X POST https://api.rymi.live/v1/agents/3a07...agent/testers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "officer@example.gov.in", "minutes_limit": 30 }'

Response 201: { "tester": { ... }, "invite_sent": true }. invite_sent: false means Rymi created the invite but the email didn't go out; use Resend.

Update a Tester

PATCH/v1/agents/:id/testers/:testerId

Send minutes_limit and/or expires_at. Changing minutes_limit also clears a pending "ask for more minutes" request.

Resend the Invite

POST/v1/agents/:id/testers/:testerId/resend

You can resend once a minute.

Revoke a Tester

DELETE/v1/agents/:id/testers/:testerId

Returns 204. The tester loses access at once.

Errors

Status	Code	Meaning
400	invalid_tester_input	Bad email, minutes outside 0 to 600, or an expiry in the past
400	free_minutes_required	The agent runs on your own provider keys, so give at least 1 free minute
403	-	Publishable keys can't manage testers
404	-	Agent or tester not found
409	tester_limit_reached	The agent already has 50 active testers
409	tester_already_invited	This email already has an active invite for the agent
429	tester_resend_cooldown	Wait a minute before resending
502	tester_invite_send_failed	The email didn't send; try again

Public Link

One link per agent. Anyone with the URL can talk to the published agent from a browser, on a pool of free minutes billed to your workspace.

Create or Update the Link

PUT/v1/agents/:id/share-link

The first call creates the link. Later calls change only the fields you send.

Field	Type	Default	Range	Description
enabled	boolean	-	-	Turn the link on or off. Off keeps the URL for later
minutes_limit	integer	30	0 to 6,000	Total free minutes shared by everyone
max_call_seconds	integer	300	60 to 1,800	Cap on one call
max_concurrent	integer	2	1 to 10	Calls running at once
calls_per_ip_hour	integer	3	1 to 30	Calls from one network per hour

cURL

curl -X PUT https://api.rymi.live/v1/agents/3a07...agent/share-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "minutes_limit": 120 }'

Node.js

const { link } = await rymi.agents.setShareLink("3a07...agent", { enabled: true, minutes_limit: 120 });
console.log(link.url);

Python

link = rymi.agents.set_share_link("3a07...agent", enabled=True, minutes_limit=120)["link"]
print(link["url"])

Response 200

{
  "link": {
    "id": "c2de...",
    "url": "https://studio.rymi.live/s/7lh15TLC4VcY...",
    "enabled": true,
    "minutes_limit": 120,
    "minutes_used": 4,
    "minutes_reserved": 0,
    "minutes_remaining": 116,
    "live_calls": 0,
    "max_call_seconds": 300,
    "max_concurrent": 2,
    "calls_per_ip_hour": 3,
    "minutes_requested_at": null
  }
}

minutes_requested_at is set when a visitor asked for more minutes. Raising minutes_limit clears it.

Get the Link

Read link from List Testers. Node: rymi.agents.getShareLink(id). Python: rymi.agents.get_share_link(id).

Regenerate the Link

POST/v1/agents/:id/share-link/regenerate

Issues a new URL and returns the same shape as above. The old URL stops working at once. Node: rymi.agents.regenerateShareLink(id). Python: rymi.agents.regenerate_share_link(id).

Errors

Status	Meaning
400	A setting is out of range or the wrong type
403	Publishable keys can't manage links
404	Agent not found, share links are off on this deployment, or (regenerate) the agent has no link yet

Visitors on the link page can hit these: 409 share_link_off, 409 share_link_unpublished, 409 share_link_pool_empty, 409 share_link_busy (all max_concurrent slots in use) and 429 share_link_rate_limited.

MCP: get_share_link, set_share_link, regenerate_share_link.