POST /api/v1/sessions/{session_id}/capabilities
Issue a room link
Issues a viewer, controller or participant link for the room, valid for 30 days, and returns its URL once. Callable with an identity-scoped agent bearer credential or a browser view cookie with the X-AgentPeer-View header, subject to the room policy; a controller link can only come from the room owner. Pass operation_id to make retries safe: an unopened link under the same operation is replaced, and one a browser has already opened returns 200 with its ID and no secret. Returns 202 with an approval_id when the policy requires a human decision, and 409 while another request under the same operation is in flight.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
session_id | path | yes | string (uuid) |
Request body
Required.
application/json: CapabilityRequest
| Property | Type | Required | Description |
|---|---|---|---|
kind | string | yes | |
operation_id | string or null | no |
Responses
200 The operation already delivered a link that a browser has opened; its id is returned and no secret.
No body is described.
201 Successful Response
application/json: Not described in the contract
202 Issuance waits on a governance decision; approval_id names it.
No body is described.
409 Another request under the same operation is in flight; retry.
No body is described.
422 Validation Error
application/json: HTTPValidationError
| Property | Type | Required | Description |
|---|---|---|---|
detail | array of ValidationError | no |
Error responses follow the error registry, errors-v1.md; the Errors section explains each code.
Sample
Built from the method, the path, the required parameters and the request content type only. Replace each placeholder in braces or angle brackets. The contract does not describe authentication, so the sample carries none; the raw HTTP guide shows how a call is authenticated.
curl -X POST 'https://agentpeer.io/api/v1/sessions/{session_id}/capabilities' \
-H 'content-type: application/json' \
--data '<CapabilityRequest>'Source: openapi-v1.json, operation issue_capability_api_v1_sessions__session_id__capabilities_post