OpenAPI YAMLOpenAPI JSONproblems YAMLAPI overview
This group has 9 operations, generated from api/openapi.yaml. Filter by path, action, or authentication. Each endpoint lists its inputs; expand it for a request template and response codes. Templates need your own values and a schema-valid body.
Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.
Service clients
List Service Clients
The project's service clients (spec: a customer's server, script or CI job owned by the project), newest first, live and revoked, with their public keys, secret ids and usage; never a secret or its digest. Needs the project capability.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
Request template and responses
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/service-clients'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientList (application/json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Create Service Client
Creates a service client owned by the project with a name, capabilities (omitted means all six; each must be one the manager holds, else 403), access (read, the default, or manage), and a public JWK key (OKP Ed25519, EC P-256 or RSA of at least 2048 bits) and/or secret true. The secret is returned once, here only. At most 50 live clients per organization.
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 201 | The service client. | ServiceClientResult (application/json) |
| 402 | feature_not_in_plan — an upload scope makes an uploader, and the project's plan does not include uploaders; required_plan names the plan that does. Narrowing a scope and removing it are always allowed. | Problem (application/problem+json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Get Service Client
One of the project's service clients. Needs the project capability.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required |
Request template and responses
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClient (application/json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Update Service Client
Renames a service client or changes its capabilities (within the manager's) or access. Narrowing either ends the client's current tokens within seconds.
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientResult (application/json) |
| 402 | feature_not_in_plan — an upload scope makes an uploader, and the project's plan does not include uploaders; required_plan names the plan that does. Narrowing a scope and removing it are always allowed. | Problem (application/problem+json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Add Service Client Key
Registers a second public JWK (key in the body) for a zero-downtime rotation; a client holds at most two.
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/keys'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientResult (application/json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Remove Service Client Key
Removes a key; the client's current tokens end within seconds. A client keeps at least one key or secret.
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required | |
| kid | path | required |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/keys/KID/remove'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientResult (application/json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Add Service Client Secret
Generates a second secret, returned once, for a zero-downtime rotation; a client holds at most two.
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/secrets'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientResult (application/json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Remove Service Client Secret
Removes a secret; the client's current tokens end within seconds.
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required | |
| secret_id | path | required |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/secrets/SECRET_ID/remove'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientResult (application/json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |
Revoke Service Client
Revokes a service client permanently: its keys and secret digests are deleted, the record stays for audit, and its tokens end within seconds (propagation applied or pending).
Agents need identity scope, live identity Manage, their own Manage grant with the project capability on the project, and a live organization admin role; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.
A member limited to screens does not connect agents, issue credentials or manage the project's people: outside_screen_scope (ask the project owner).
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| ScreenRig-Project | header | optional | Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange. |
| id | path | required |
Request body fields
| Field | Description |
|---|---|
| project_id (optional, string) | Dashboard session only. |
| proof (optional, DashboardProof) | |
| name (optional, string) | minLength: 1 maxLength: 80 |
| capabilities (optional, array) | |
| access (optional, string) | Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage" |
| key (optional, object) | A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits. |
| secret (optional, boolean) | Generate a secret (creation only). |
| upload_scope (optional, UploadScope) | What an uploader may use (docs/uploaders.md): the playlists it changes pages of and the media folders it uploads into. Folders are exactly the listed ones, never their subfolders. An id that names no live object of the project when written is invalid_request at its position; a later deletion leaves a dead id, which grants nothing. The scope is read on each request, so a change applies to the next one. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/revoke'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The service client. | ServiceClientResult (application/json) |
| 403 | outside_screen_scope - the caller is limited to screens and the screen, screen folder, selector or audience the request names or reaches is outside them (docs/screen-scope.md). An id outside the scope and an id that does not exist get the same answer; errors[0].screen_scope carries the caller's scope, and the write is refused whole, never narrowed. | Problem (application/problem+json) |
| default | Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | Problem (application/problem+json) |