Comments API Reference: Endpoints and Examples

OpenAPI YAML OpenAPI JSON problems YAML API 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.

Comments

GET/api/comment/screen/{id}¶

Get Screen Comments

Opaque agent comments on the named screen. ScreenRig does not read or use them. They are not authorization and are not on the runtime manifest. A screen with no comments returns comments null. Archived screens remain addressable. Authenticated /api control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getScreenComments

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

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/screen/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (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)

PUT/api/comment/screen/{id}¶

Put Screen Comments

Replaces opaque agent comments on the named screen. The comments value must be a JSON object whose compact UTF-8 form is at most 1024 bytes. Last-write-wins on the comments field only; revision, updated_at, and the runtime manifest are unchanged.

Authentication: projectBearer
Request body: CommentsWrite
Operation ID: putScreenComments

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
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
comments (required, object)	Opaque agent JSON object. Compact UTF-8 serialization must be at most 1024 bytes. Nested objects, arrays, and strings are allowed. Arrays, strings, numbers, booleans, and null are rejected as the comments value itself.

Request template and responses

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/comment/screen/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (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)

DELETE/api/comment/screen/{id}¶

Delete Screen Comments

Unsets screen comments. Idempotent if already unset. Does not bump revision or remint the runtime manifest.

Authentication: projectBearer
Request body: none
Operation ID: deleteScreenComments

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
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/screen/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Unset	no body
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/api/comment/playlist/{id}¶

Get Playlist Comments

Opaque agent comments on the named playlist. ScreenRig does not read or use them. A playlist with no comments returns comments null. Authenticated /api control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistComments

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

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (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)

PUT/api/comment/playlist/{id}¶

Put Playlist Comments

Replaces opaque agent comments on the named playlist. Compact UTF-8 JSON of the comments object must be at most 1024 bytes. Last-write-wins on the comments field only; revision and the runtime manifest are unchanged.

Authentication: projectBearer
Request body: CommentsWrite
Operation ID: putPlaylistComments

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
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
comments (required, object)	Opaque agent JSON object. Compact UTF-8 serialization must be at most 1024 bytes. Nested objects, arrays, and strings are allowed. Arrays, strings, numbers, booleans, and null are rejected as the comments value itself.

Request template and responses

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (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)

DELETE/api/comment/playlist/{id}¶

Delete Playlist Comments

Unsets playlist comments. Idempotent if already unset. Does not bump revision or remint the runtime manifest.

Authentication: projectBearer
Request body: none
Operation ID: deletePlaylistComments

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
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Unset	no body
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/api/comment/playlist/{id}/page/{page_id}¶

Get Playlist Page Comments

Opaque agent comments on one playlist page, addressed by the page id string. A page with no comments returns comments null. Missing playlist or page is not_found. Authenticated /api control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistPageComments

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
page_id	path	required	Playlist page id string.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID/page/PAGE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (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)

PUT/api/comment/playlist/{id}/page/{page_id}¶

Put Playlist Page Comments

Replaces opaque agent comments on one playlist page. Compact UTF-8 JSON of the comments object must be at most 1024 bytes. Last-write-wins on that page's comments field only; playlist revision and the runtime manifest are unchanged.

Authentication: projectBearer
Request body: CommentsWrite
Operation ID: putPlaylistPageComments

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
page_id	path	required	Playlist page id string.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
comments (required, object)	Opaque agent JSON object. Compact UTF-8 serialization must be at most 1024 bytes. Nested objects, arrays, and strings are allowed. Arrays, strings, numbers, booleans, and null are rejected as the comments value itself.

Request template and responses

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID/page/PAGE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (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)

DELETE/api/comment/playlist/{id}/page/{page_id}¶

Delete Playlist Page Comments

Unsets comments on one playlist page. Idempotent if already unset. Does not bump revision or remint the runtime manifest.

Authentication: projectBearer
Request body: none
Operation ID: deletePlaylistPageComments

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
page_id	path	required	Playlist page id string.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID/page/PAGE_ID'

Responses

Status	Meaning	Body and headers
204	Unset	no body
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)