{ "openapi": "3.1.0", "info": { "description": "Redocly platform API is a REST API over HTTPS for accessing and managing Redocly platform resources.\n\nThe API supports the following use cases:\n\n- Automation of organization and project workflows\n- Integration with internal systems\n- Development of customer-facing integrations\n\nTechnical characteristics:\n\n- Resource-oriented URLs\n- JSON request and response bodies\n- Standard HTTP methods and status codes\n- Filtering and search on selected collection endpoints\n\nEndpoint availability depends on subscription plan, organization settings, and product rollout status.\nThe API description is the authoritative reference.\nOrganizations for which an endpoint is not enabled should contact support.\n\n## Authentication\n\nThe API uses API keys for authentication.\nAuthentication requirements are defined per operation in the API description.\n\nAPI keys are intended for server-to-server integration.\nAPI keys are created as described in [Manage API keys](https://redocly.com/docs/realm/reunite/organization/api-keys).\nThe key is transmitted as a Bearer token:\n\n```http\nAuthorization: Bearer \n```\n\nKeys must meet the following requirements:\n\n- Stored in a secure secret management system (not in client-side application code)\n- Rotated on a regular basis\n- Revoked when no longer required\n- Limited to the minimum set of endpoints and environments necessary for the integration\n\nEvery operation states the authentication it accepts in its own `security` section.\nTypical responses include:\n\n- `401 Unauthorized` (missing, invalid, or expired credentials)\n- `403 Forbidden` (credentials are valid but insufficient for the requested action)\n\n## Pagination\n\nList endpoints implement cursor-based pagination.\nEach response includes a `page` object and the results in the `data` array.\n\nSupported query parameters:\n\n- `limit`: values from `1` to `100`, default `10`\n- `after` and `before`: cursor navigation\n- `sort`: for example `-id` or `id`\n\nThe `page` object contains:\n\n- `nextPage`: the path of the next page, or `null` when there is no next page\n- `previousPage`: the path of the previous page, or `null` when there is no previous page\n- `limit`\n\n`nextPage` and `previousPage` are paths relative to the API server URL.\nThey keep the query parameters of the request, such as `limit`, `filter`, and `sort`.\n`nextPage` sets `after` to the cursor of the next page, and `previousPage` sets `before` to the cursor of the previous page.\nTo get the adjacent page, append the value to the server URL as a string:\n\n```text\nhttps://app.cloud.redocly.com/api + /orgs/org_123/projects?limit=10&after=a25fgaksjf23la==\n= https://app.cloud.redocly.com/api/orgs/org_123/projects?limit=10&after=a25fgaksjf23la==\n```\n\nDo not resolve the value as a relative URL, for example with `new URL(nextPage, serverUrl)`.\nThe leading `/` replaces the `/api` path of the server URL.\n\nA typical sequence:\n\n1. Request the first page with `?limit=10`.\n2. Read `page.nextPage`.\n3. Request the server URL followed by `page.nextPage`.\n4. Continue until `nextPage` is `null`.\n\nThe cursors are opaque, and their internal structure is subject to change.\nTo build a request yourself, send the `after` value from `nextPage`, or the `before` value from `previousPage`, with your other query parameters.\n\n## Filter results\n\n**Filtering** uses the `?filter=` parameter with `field:value` syntax.\nThe supported forms include:\n\n- Exact match: `firstName:Casey`\n- Case-insensitive substring match: `firstName~jo`\n- Multiple values: `firstName:Casey,Jordan`, `status:success,pending`\n- Numeric or date-time ranges: `amount:1..10`, ISO 8601 date-times\n- Relative durations for date-time fields: `30d`, `2w`, `6mo`, `1y`, `all` (units: `s`, `m`, `h`, `d`, `w`, `mo`, `y`)\n- Nested fields: `team.user.email:casey.smith@acme-inc.com`\n- Negation: `-firstName:Casey`\n- Logical operators: `AND`, `OR`\n\nCombine multiple conditions by separating `field:value` pairs with a space.\nA space is treated as an implicit `AND`, so `firstName:Casey isAdmin:true` and `firstName:Casey AND isAdmin:true` are equivalent.\nUse `OR` to match alternatives.\n`AND` binds more tightly than `OR`, so `role:admin OR role:editor isActive:true` is evaluated as `role:admin OR (role:editor AND isActive:true)`.\nGrouping with parentheses is not supported.\n\nFor a single-valued field, comma-separated values and `OR` are equivalent: `role:admin,editor` matches the same records as `role:admin OR role:editor`.\nThey are not interchangeable when the field targets a to-many relation, when negation is applied (`-role:admin,editor` matches neither value, whereas `-role:admin OR -role:editor` matches every record), or when matching `null`.\n\nExplicit date-time values use ISO 8601.\nValues that contain spaces, commas, or `..` must be enclosed in quotation marks.\n`number`, `boolean`, and `null` values do not require quotation marks.\n\n```text\n?filter=firstName:Casey\n?filter=firstName~jo\n?filter=firstName:Casey,Jordan\n?filter=amount:1..10\n?filter=createdAt:30d\n?filter=team.user.email:casey.smith@acme-inc.com\n?filter=-firstName:Casey\n?filter=firstName:Casey isAdmin:true\n?filter=firstName:Casey AND isAdmin:true\n?filter=role:admin OR role:editor\n?filter=createdAt:2021-02-14T13:30:00.000Z\n?filter=description:\"The story called \\\"The Sky and the Sea.\\\"\"\n?search=casey\n```\n\n**Search** uses the `?search=` parameter where the operation supports it.\nIts behavior is defined per endpoint in the API description.\n\n## Errors\n\nError responses commonly use the `application/problem+json` media type.\nFields may include:\n\n- `type`\n- `title`\n- `status`\n- `detail` (optional)\n- `instance` (optional)\n- `object` (always `problem`)\n- `requestId` (optional)\n- `errors` (optional array)\n\nFrequently returned HTTP status codes:\n\n- `400`: validation failure or malformed input\n- `401`: authentication failure\n- `403`: authorization failure\n- `404`: resource not found\n- `409`: conflict with current state\n- `429`: rate limit exceeded\n- `500`: server error\n\nAdditional behavior:\n\n- Certain endpoints may return `402` when access depends on subscription plan or billing state.\n\nTroubleshooting:\n\n- Begin with the HTTP status code.\n- Review the `detail` and `errors` fields.\n\nInclude the following in support requests:\n\n- The complete response payload\n- Sufficient request context to reproduce the issue\n\n## Rate limits\n\nRate limiting preserves service stability and equitable usage.\n\nThe API description defines limits with the `x-rateLimit` extension.\nThese organization quotas apply to requests authenticated with an **API key** that belongs to your organization.\nExample properties:\n\n- `events` - the number of events allowed within the window\n- `window` - the length of the window, for example `1m`\n\nEnforcement:\n\n- For API keys, limits apply **per organization**: all API keys for the same organization share a single counter for a given limit.\n- Unauthenticated traffic to public endpoints does **not** consume these organization counters.\n It is limited separately (for example by per-client protections at the edge).\n This mechanism prevents anonymous callers from exhausting an organization's quota.\n- Limits may be defined per endpoint.\n- Limits may be overridden per organization or per endpoint.\n\nWhen a request exceeds the applicable limit, the API returns `429 Too Many Requests` and includes a `Retry-After` header with the number of seconds to wait before the next request.\n\nSend requests for increased throughput to `team@redocly.com` and include:\n\n- Organization ID\n- Affected endpoints\n- Expected request rate\n- Business justification\n", "version": "1.0.1", "title": "Redocly platform", "termsOfService": "https://redocly.com/subscription-agreement", "contact": { "name": "API Support", "email": "team@redocly.com", "url": "https://github.com/Redocly/redocly" }, "license": { "name": "Redocly", "url": "https://redocly.com/subscription-agreement" } }, "servers": [ { "url": "https://app.cloud.redocly.com/api", "description": "Production main server." }, { "url": "https://app.cloud.eu.redocly.com/api", "description": "Production EU server." } ], "tags": [ { "name": "Audit log exports", "description": "Export organization audit logs for compliance, analysis, or archival." }, { "name": "Feedback", "description": "Operations related to feedback." }, { "name": "Pushes", "description": "Operations related to pushes." } ], "paths": { "/orgs/{orgId}/audit-log-export-jobs": { "post": { "tags": [ "Audit log exports" ], "security": [ { "ApiKey": [] } ], "operationId": "createAuditLogExportJob", "summary": "Start an audit log export job", "description": "{% configOptionRequirements plans=[\"Enterprise+\"] /%}\n\nCreates an asynchronous audit log export job.\nPoll the job status endpoint until `status` is `COMPLETED`, then download from the export results endpoint.", "x-rateLimit": { "events": 60, "window": "1m" }, "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "name": "filter", "in": "query", "required": false, "description": "Standard list `filter` query. Supported fields for audit exports:\n- `type` — Event type.\n When omitted, exports include events of all types.\n Values must be valid audit log event types.\n Unsupported values return `400`.\n\nFilter fields other than `type` are ignored.", "schema": { "type": "string" }, "example": "type:com.redocly.apiKey.created" }, { "name": "start", "in": "query", "description": "Start of the time range in YYYY-MM-DD format. When `end` is omitted, exports include events from `start` through `start + 31 days`.", "required": false, "example": "2026-01-01", "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "End of the time range in YYYY-MM-DD format. When `start` is omitted, exports include events from `end - 31 days` through `end`. The time window between `start` and `end` must not exceed 31 days.", "required": false, "example": "2026-01-31", "schema": { "type": "string", "format": "date" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "description": "Output file format for the generated download.", "example": "json" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "201": { "description": "Export job created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogExportJobCreated" }, "example": { "id": "exp_01hh1t9sa6gwfv5naz04gr7ehm", "createdAt": "2024-01-15T12:00:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/audit-log-export-jobs/{exportJobId}": { "get": { "tags": [ "Audit log exports" ], "security": [ { "ApiKey": [] } ], "operationId": "getAuditLogExportJob", "summary": "Retrieve an audit log export job", "description": "{% configOptionRequirements plans=[\"Enterprise+\"] /%}\n\nRetrieve the status of an audit log export job.\nPoll this endpoint until `status` is `COMPLETED`, then download the file from the export results endpoint.", "x-rateLimit": { "events": 300, "window": "1m" }, "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ExportJobId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "Export job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogExportJob" }, "example": { "id": "exp_01hh1t9sa6gwfv5naz04gr7ehm", "status": "COMPLETED", "createdAt": "2024-01-15T12:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/audit-log-export-results/{exportJobId}": { "get": { "tags": [ "Audit log exports" ], "security": [ { "ApiKey": [] } ], "operationId": "getAuditLogExportResult", "summary": "Retrieve an audit log export file", "description": "{% configOptionRequirements plans=[\"Enterprise+\"] /%}\n\nDownload the file generated by an audit log export job.\nThe file is available only after the export job completes.\nWhile the job status is `IN_PROGRESS` or `FAILED`, this endpoint returns `404`.", "x-rateLimit": { "events": 60, "window": "1m" }, "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ExportJobId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "Export file. Media type matches the `format` from the create-job request.", "headers": { "Content-Disposition": { "description": "Attachment hint for browsers and HTTP clients. Suggested filename: `{exportJobId}.json` or `{exportJobId}.csv`.", "schema": { "type": "string" }, "example": "attachment; filename=\"exp_01hh1t9sa6gwfv5naz04gr7ehm.json\"" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogExportEvent" } }, "example": [ { "id": "evt_2fxb8r4kq7m3ndp9z6ja501", "object": "event", "type": "com.redocly.pullRequest.created", "time": "2026-03-31T15:27:30.815Z", "subject": "pr_7wnk3jm9xp2d4rv8qh5a01", "actor": { "id": "usr_01h2r5f6qy8kr42p8yfw52spq6", "object": "user", "uri": "https://app.cloud.redocly.com/api/users/usr_01h2r5f6qy8kr42p8yfw52spq6" }, "clientIp": "198.51.100.42", "projectId": "prj_01hh1t9sa6gwfv5naz04gr7ehm", "projectSlug": "my-project" } ] }, "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "id,object,type,time,subject,actor,clientIp,projectId,projectSlug\nevt_2fxb8r4kq7m3ndp9z6ja501,event,com.redocly.pullRequest.created,2026-03-31T15:27:30.815Z,pr_7wnk3jm9xp2d4rv8qh5a01,\"{\"\"id\"\":\"\"usr_01h2r5f6qy8kr42p8yfw52spq6\"\",\"\"object\"\":\"\"user\"\",\"\"uri\"\":\"\"https://app.cloud.redocly.com/api/users/usr_01h2r5f6qy8kr42p8yfw52spq6\"\"}\",198.51.100.42,prj_01hh1t9sa6gwfv5naz04gr7ehm,my-project\n" } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/projects/{projectId}/feedback": { "get": { "tags": [ "Feedback" ], "summary": "List all feedback", "description": "List all feedback.\n\nRequires `project.feedback.read` permission.", "x-rateLimit": { "events": 300, "window": "1m" }, "operationId": "listFeedback", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/Before" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Sort", "description": "Feedback list can be sorted by the following properties:\n - `id`\n - `createdAt`\n - `path`\n - `email`\n - `score`\n - `agent`\n - `targetFeature`\n\nTo sort in descending order, prefix the field with `-` (for example `-createdAt`).\nTo sort in ascending order, use the field name without a prefix (for example `createdAt`).\n\nBy default, feedback list is sorted by `id` in descending order, which corresponds to the newest feedback first." }, { "$ref": "#/components/parameters/Filter", "description": "Filter feedback by:\n - `createdAt`\n - `email`\n - `path`\n - `location`\n - `comment`\n - `internalComment`\n - `agent`\n - `targetFeature`\n - `status` (one of `NEW`, `IN_REVIEW`, `RESOLVED`, `ARCHIVED`, `SPAM`)\n - `feedbackComponent` (one of `SENTIMENT`, `RATING`, `COMMENT`, `MOOD`, `PROBLEM`, `SCALE`)\n - `origin` (one of `FORM`, `API`, `MCP`)\n\nThis field requires a special format.\n\nFor more information, see [Filter results](#section/filter-results)." }, { "$ref": "#/components/parameters/Search", "description": "Search feedback by query string.\n\nFeedback is searched by:\n - `email`\n - `path`\n - `location`\n - `comment`\n - `internalComment`\n - `agent`\n - `targetFeature`" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackList" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/projects/{projectId}/feedback/{feedbackId}": { "get": { "tags": [ "Feedback" ], "security": [ { "ApiKey": [] } ], "summary": "Retrieve a feedback item", "description": "Retrieve a feedback item.\n\nRequires `project.feedback.read` permission.", "x-rateLimit": { "events": 2000, "window": "1m" }, "operationId": "getFeedback", "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/FeedbackId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Feedback" ], "security": [ { "ApiKey": [] } ], "summary": "Partially update a feedback item", "description": "Partially update a feedback item.\n\nRequires `project.feedback.update` permission.", "x-rateLimit": { "events": 300, "window": "1m" }, "operationId": "updateFeedback", "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/FeedbackId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchFeedbackRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Feedback" ], "security": [ { "ApiKey": [] } ], "summary": "Delete a feedback item", "description": "Delete a feedback item.\n\nRequires `project.feedback.delete` permission.", "x-rateLimit": { "events": 300, "window": "1m" }, "operationId": "deleteFeedback", "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/FeedbackId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/projects/{projectId}/feedback-export": { "get": { "tags": [ "Feedback" ], "summary": "Export feedback report", "description": "Download a feedback report as CSV or JSON file.\nResponse Content-Type is `text/csv` when `format=csv` and `application/json` when `format=json`.\n\nRequires `project.feedback.read` permission.", "x-rateLimit": { "events": 10, "window": "1m" }, "operationId": "exportFeedbackReport", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "name": "format", "in": "query", "required": false, "description": "Export file format. Defaults to `csv`.", "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "csv" }, "example": "csv" }, { "$ref": "#/components/parameters/After", "description": "Cursor from `page.nextPage` in a **List all feedback** response.\nThe export includes only the rows after this cursor." }, { "$ref": "#/components/parameters/Before", "description": "Cursor from `page.previousPage` in a **List all feedback** response.\nThe export includes only the rows before this cursor." }, { "name": "limit", "description": "Maximum number of feedback rows to include in the export (from the current sort order).\n\nWhen omitted, the export includes up to 1000 rows.\nRequest a larger export explicitly, up to the maximum.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000 }, "example": 10000 }, { "$ref": "#/components/parameters/Sort", "description": "Feedback report can be sorted by the following properties:\n - `id`\n - `createdAt`\n - `path`\n - `email`\n - `score`\n - `agent`\n - `targetFeature`\n\nTo sort in descending order, prefix the field with `-` (for example `-createdAt`).\nTo sort in ascending order, use the field name without a prefix (for example `createdAt`).\n\nBy default, feedback report is sorted by `id` in descending order, which corresponds to the newest feedback first." }, { "$ref": "#/components/parameters/Filter", "description": "Filter feedback by:\n - `createdAt`\n - `email`\n - `path`\n - `location`\n - `comment`\n - `internalComment`\n - `agent`\n - `targetFeature`\n - `status` (one of `NEW`, `IN_REVIEW`, `RESOLVED`, `ARCHIVED`, `SPAM`)\n - `feedbackComponent` (one of `SENTIMENT`, `RATING`, `COMMENT`, `MOOD`, `PROBLEM`, `SCALE`)\n - `origin` (one of `FORM`, `API`, `MCP`)\n\nThis field requires a special format.\n\nFor more information, see [Filter results](#section/filter-results)." }, { "$ref": "#/components/parameters/Search", "description": "Search feedback by query string.\n\nFeedback is searched by:\n - `email`\n - `path`\n - `location`\n - `comment`\n - `internalComment`\n - `agent`\n - `targetFeature`" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "Export file.\nMedia type depends on the `format` query parameter.\n\nThe response is sent as a download: `Content-Disposition` is `attachment` with a generated filename unless the server chooses otherwise.\n\nDefault filename pattern: `feedback_export_{orgId}_{projectId}_{timestamp}.{format}`, where `{timestamp}` is milliseconds since the Unix epoch and `{format}` is either `csv` or `json`.", "headers": { "Content-Disposition": { "description": "Attachment hint for browsers and HTTP clients.\nIncludes the suggested filename in the `filename` parameter (quoted).\n\nBy default the filename follows `feedback_export_{orgId}_{projectId}_{timestamp}.{format}`, using the same `orgId` and `projectId` as in the path and a millisecond timestamp.", "schema": { "type": "string" }, "example": "attachment; filename=\"feedback_export_org_01hh1t9sa6gwfv5naz04gr7ehm_prj_01hh1t9sa6gwfv5naz04gr7ehm_1715432100123.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/projects/{projectId}/pushes": { "post": { "operationId": "push", "summary": "Push files to remote", "x-rateLimit": { "events": 300, "window": "1m" }, "security": [ { "ApiKey": [] } ], "description": "Push discovered files as a remote content.\nFiles should be sent as a `multipart/form-data`.\nCommit details like commit message and author can be sent as a JSON object in the `commit` field.\nThe complete multipart body must not exceed 500 MiB, including files, fields, and multipart overhead.\n\nRequires `project.remotes.update` permission.\nThe CLI `push` command creates or updates the remote before it pushes files, so it also requires `project.remotes.create`.", "tags": [ "Pushes" ], "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Push" } } } }, "responses": { "201": { "description": "Content pushed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Push" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "description": "Push body exceeds 500 MiB.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Pushes" ], "security": [ { "ApiKey": [] } ], "summary": "List all pushes", "description": "List all pushes.\n\nRequires `project.remotes.read` permission.", "x-rateLimit": { "events": 300, "window": "1m" }, "operationId": "listPushes", "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/Before" }, { "$ref": "#/components/parameters/Sort", "description": "Push list can be sorted by `id` only.\n\nTo sort in descending order, use `-id`.\nTo sort in ascending order, use `id`.\n\nBy default, push list is sorted by `id` in descending order, which corresponds to the newest pushes first." }, { "$ref": "#/components/parameters/Filter", "description": "Filter pushes by:\n - `id`\n - `isMainBranch`\n - `replace`\n - `scoutJobId`\n\nThis field requires a special format.\n\nFor more information, see [Filter results](#section/filter-results)." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Search", "description": "Search pushes by query string.\n\nPushes are searched by:\n - `id`\n - `scoutJobId`\n - `isMainBranch` and `replace`, only when the search term is exactly `true` or `false`" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushList" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orgs/{orgId}/projects/{projectId}/pushes/{pushId}": { "get": { "security": [ { "ApiKey": [] } ], "tags": [ "Pushes" ], "operationId": "getPush", "summary": "Retrieve a push", "description": "Retrieve a push.\n\nRequires `project.remotes.read` permission.", "x-rateLimit": { "events": 2000, "window": "1m" }, "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/PushId" }, { "name": "x-redocly-client", "in": "header", "required": false, "description": "Identifies the calling client as `/`, for example `reunite-ui/0.92.1`.\nUsed for API consumer observability.\nRequests without it are attributed as `unknown`.\n", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}/[\\w.+-]{1,32}$" }, "example": "reunite-ui/0.92.1" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Push" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "Problem": { "type": "object", "title": "Problem", "properties": { "type": { "type": "string", "format": "uri-reference", "description": "URI reference that uniquely identifies the problem type only in the context of the provided API.\nOpposed to the specification in RFC 9457 (formerly RFC 7807), it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.\n", "default": "about:blank", "example": "/some/uri-reference" }, "title": { "type": "string", "description": "Short summary of the problem type.\nWritten in English and readable for engineers, usually not suited for non technical stakeholders and not localized.\n", "example": "some title for the error situation" }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code generated by the origin server for this occurrence of the problem.\n", "minimum": 100, "exclusiveMaximum": 600, "example": 400 }, "detail": { "type": "string", "description": "Human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed.\nWritten in English and readable for engineers, usually not suited for non technical stakeholders and not localized.\n", "example": "some description for the error situation" }, "instance": { "type": "string", "format": "uri-reference", "description": "URI reference that identifies the specific occurrence of the problem. For example, by adding a fragment identifier or sub-path to the problem type.\nMay be used to locate the root of this problem in the source code.\n", "example": "/some/uri-reference#specific-occurrence-context" }, "object": { "type": "string", "enum": [ "problem" ] }, "requestId": { "type": "string", "description": "Unique identifier of the request that produced this problem.\nShare it with support when reporting the error.\n", "example": "req-abc-123" }, "errors": { "type": "array", "description": "Additional information about the error situation.\nMay be omitted if no additional information is available.\n" } }, "required": [ "type", "title", "status", "object" ] }, "Page": { "type": "object", "properties": { "nextPage": { "type": [ "string", "null" ], "format": "uri-reference", "description": "Path of the next page, relative to the API server URL.\nAppend the value to the server URL to get the next page.\nThe path keeps the query parameters of the request and sets `after` to the cursor of the next page.\nWhen `null`, there is no next page.", "example": "/orgs/org_123/projects?limit=10&after=a25fgaksjf23la==" }, "previousPage": { "type": [ "string", "null" ], "format": "uri-reference", "description": "Path of the previous page, relative to the API server URL.\nAppend the value to the server URL to get the previous page.\nThe path keeps the query parameters of the request and sets `before` to the cursor of the previous page.\nWhen `null`, there is no previous page.", "example": "/orgs/org_123/projects?limit=10&before=bfg23aksjf23zb1==" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Value showing how many items are in the page limit." } }, "required": [ "nextPage", "previousPage", "limit" ] }, "AuditLogExportJobCreated": { "type": "object", "description": "Details of the created audit log export job.", "properties": { "id": { "readOnly": true, "type": "string", "pattern": "^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier for the export job, prefixed with `exp_`.", "example": "exp_01hh1t9sa6gwfv5naz04gr7ehm" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Export job creation time (ISO 8601)." } }, "required": [ "id", "createdAt" ] }, "AuditLogExportStatus": { "type": "string", "description": "Current status of the export job.", "enum": [ "IN_PROGRESS", "COMPLETED", "FAILED" ] }, "AuditLogExportJob": { "type": "object", "description": "Audit log export job status and metadata.", "properties": { "id": { "readOnly": true, "type": "string", "pattern": "^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier for the export job, prefixed with `exp_`.", "example": "exp_01hh1t9sa6gwfv5naz04gr7ehm" }, "status": { "$ref": "#/components/schemas/AuditLogExportStatus" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Export job creation time (ISO 8601)." } }, "required": [ "id", "status", "createdAt" ] }, "AuditLogEventType": { "type": "string", "description": "CloudEvent `type` value emitted for an audit-loggable action.\nOnly events whose `type` is in this list are returned by the audit log export endpoints.", "enum": [ "com.redocly.apiKey.created", "com.redocly.apiKey.updated", "com.redocly.apiKey.revoked", "com.redocly.gitIdentity.linked", "com.redocly.gitIdentity.unlinked", "com.redocly.gitIdentity.removed", "com.redocly.scimCredential.created", "com.redocly.scimCredential.revoked", "com.redocly.invite.created", "com.redocly.invite.resent", "com.redocly.userInvite.accepted", "com.redocly.membership.created", "com.redocly.membership.updated", "com.redocly.membership.removed", "com.redocly.team.created", "com.redocly.team.deleted", "com.redocly.teamMember.added", "com.redocly.teamMember.removed", "com.redocly.syncedTeamMember.added", "com.redocly.syncedTeamMember.removed", "com.redocly.teamManager.added", "com.redocly.teamManager.removed", "com.redocly.organization.created", "com.redocly.organization.updated", "com.redocly.organization.slugUpdated", "com.redocly.organization.removed", "com.redocly.project.created", "com.redocly.project.updated", "com.redocly.project.slugUpdated", "com.redocly.project.urlUpdated", "com.redocly.project.removed", "com.redocly.projectConfig.updated", "com.redocly.projectCustomDomain.verified", "com.redocly.projectCustomDomain.removed", "com.redocly.branch.created", "com.redocly.branch.updated", "com.redocly.branch.removed", "com.redocly.gitAccess.pushed", "com.redocly.remote.created", "com.redocly.remote.deleted", "com.redocly.gitCredential.rotated", "com.redocly.notificationSettings.updated", "com.redocly.notifications.disabled", "com.redocly.subscription.updated", "com.redocly.subscription.churned", "com.redocly.subscription.reactivated", "com.redocly.subscription.trialEnded", "com.redocly.pullRequest.created", "com.redocly.pullRequest.closed", "com.redocly.pullRequest.reopened", "com.redocly.pullRequest.merged", "com.redocly.pullRequest.approved", "com.redocly.pullRequest.requestedChanges", "com.redocly.pullRequest.reviewRequested", "com.redocly.pullRequest.readyForReview", "com.redocly.pullRequest.markedAsDraft", "com.redocly.pullRequest.commented", "com.redocly.pullRequest.commitPushed", "com.redocly.pullRequest.forcePushed", "com.redocly.pullRequest.visualReviewUpdated" ], "example": "com.redocly.pullRequest.created" }, "id": { "description": "Project ID. Unique identifier prefixed with `prj_`.", "type": "string", "pattern": "^prj_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "example": "prj_01hh1t9sa6gwfv5naz04gr7ehm", "readOnly": true }, "slug": { "description": "Project slug.", "type": "string", "example": "project_red-owl-352" }, "AuditLogExportEvent": { "type": "object", "description": "One audit log export record.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "Unique event identifier.", "example": "evt_2fxb8r4kq7m3ndp9z6ja501" }, "object": { "type": "string", "description": "Entity name.", "enum": [ "event" ], "readOnly": true }, "type": { "$ref": "#/components/schemas/AuditLogEventType" }, "time": { "type": "string", "format": "date-time", "description": "Event timestamp (ISO 8601).", "example": "2026-04-15T14:43:08.172Z" }, "subject": { "type": "string", "description": "Subject URI or resource ID the event refers to.", "example": "pr_7wnk3jm9xp2d4rv8qh5a01" }, "projectId": { "$ref": "#/components/schemas/id" }, "projectSlug": { "$ref": "#/components/schemas/slug" }, "clientIp": { "type": "string", "description": "IP address of the client that triggered the event.", "example": "198.51.100.42" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "Actor that triggered the event.", "properties": { "id": { "type": "string", "pattern": "^(usr|gid|wh|cj)_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "example": "usr_01h2r5f6qy8kr42p8yfw52spq6" }, "object": { "type": "string", "enum": [ "user", "gitIdentity", "webhook", "cronJob" ], "example": "user" }, "uri": { "type": "string", "format": "uri", "example": "https://app.cloud.redocly.com/api/users/usr_01h2r5f6qy8kr42p8yfw52spq6" } }, "required": [ "id", "object", "uri" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "Feedback": { "type": "object", "title": "Feedback", "additionalProperties": false, "properties": { "id": { "description": "Feedback ID. Unique identifier prefixed with `fb_`.", "type": "string", "pattern": "^fb_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "example": "fb_01h1s5z6vf2mm1mz3hevnn9va7", "readOnly": true }, "object": { "description": "Entity name.", "type": "string", "enum": [ "feedback" ], "readOnly": true }, "uri": { "description": "Canonical URI for the feedback resource.", "type": "string", "format": "uri", "readOnly": true, "example": "https://app.cloud.redocly.com/api/orgs/org_01hh1t9sa6gwfv5naz04gr7ehm/projects/prj_01hh1t9sa6gwfv5naz04gr7ehm/feedback/fb_01h1s5z6vf2mm1mz3hevnn9va7" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254, "description": "Email address of user who submitted the feedback or `null`." }, "path": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Absolute URL of the page where feedback is submitted (for example from the browser location). A value that is not a valid URL is accepted, but the feedback is marked as spam.", "example": "https://example.com/docs/guide" }, "location": { "type": [ "string", "null" ], "maxLength": 5000, "description": "Identifies the location of the component.\nThis could be a code sample." }, "lang": { "type": "string", "maxLength": 20, "description": "Identifies the language of the component's location.\nThis could be the language of a code sample, such as `js`, `php`, or `txt`." }, "feedbackComponent": { "type": "string", "description": "Name that identifies UI component.", "enum": [ "SENTIMENT", "RATING", "COMMENT", "MOOD", "PROBLEM", "SCALE" ] }, "score": { "description": "Numeric value that maps to the feedback component, such as thumbs down (-1) or thumbs up (1), or a 1-5 star rating scale.", "type": [ "integer", "null" ], "minimum": -1, "maximum": 10 }, "maxScore": { "description": "Maximum score for the feedback component.", "type": [ "integer", "null" ], "minimum": 0, "maximum": 10 }, "reasons": { "type": "array", "description": "List of preset reasons for feedback.", "items": { "type": "string", "maxLength": 5000, "description": "Reason for feedback." } }, "comment": { "type": "string", "maxLength": 5000, "description": "Free-form text feedback." }, "agent": { "type": [ "string", "null" ], "maxLength": 200, "description": "Name of the AI agent that submitted the feedback, or `null` for user-submitted feedback.", "example": "Cursor" }, "targetFeature": { "type": [ "string", "null" ], "maxLength": 500, "description": "Documentation feature the feedback refers to (for agent submissions), or `null` for user-submitted feedback.", "example": "Respect Monitoring API" }, "origin": { "type": "string", "description": "Origin of the feedback. `FORM` is the feedback form on the page, `API` is a direct API call (for example an agent that follows `llms.txt` instructions), and `MCP` is the MCP server `submit-feedback` tool. When omitted on create, defaults to `API` if `agent` is set and to `FORM` otherwise.", "enum": [ "FORM", "API", "MCP" ], "example": "MCP" }, "metadata": { "type": "object", "description": "Extra tracking fields. The server sets `userAgent`, `ipAddress`, `platform`, and `email` (read-only). `id`, `firstName`, `lastName`, and `auth_time` pass through if present but are not verified; do not use for access or identity. Any other key is stored with its value redacted to a placeholder.", "properties": { "userAgent": { "type": "string", "description": "User agent string of the browser that submitted the feedback. Populated by the server from the `User-Agent` header.", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", "readOnly": true }, "ipAddress": { "type": "string", "description": "IP address of the user who submitted the feedback. Populated by the server.", "example": "127.0.0.1", "readOnly": true }, "platform": { "type": "string", "description": "Platform from which the feedback originates. Populated by the server from the `Sec-Ch-Ua-Platform` header.", "example": "Windows NT 10.0; Win64; x64", "readOnly": true }, "email": { "type": "string", "format": "email", "description": "Email address from the user's authentication context. Populated by the server from OIDC claims.", "example": "john.doe@acme.com", "readOnly": true }, "id": { "type": "string", "description": "Unverified; whatever the client sent. Not a trusted user ID." }, "firstName": { "type": "string", "description": "Unverified; client-supplied if present." }, "lastName": { "type": "string", "description": "Unverified; client-supplied if present." }, "auth_time": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Unverified; client-supplied. Not a server-asserted session or token time." } }, "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "status": { "type": "string", "description": "Feedback status.", "enum": [ "NEW", "IN_REVIEW", "RESOLVED", "ARCHIVED", "SPAM" ], "example": "ARCHIVED", "readOnly": true }, "organizationId": { "description": "Organization ID. Unique identifier prefixed with `org_`.", "type": "string", "pattern": "^org_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "example": "org_01hh1t9sa6gwfv5naz04gr7ehm", "readOnly": true }, "projectId": { "description": "Project ID. Unique identifier prefixed with `prj_`.", "type": "string", "pattern": "^prj_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "example": "prj_01hh1t9sa6gwfv5naz04gr7ehm", "readOnly": true }, "internalComment": { "type": [ "string", "null" ], "description": "Internal comment for the feedback.", "example": "This feedback is related to the issue 235.", "readOnly": true }, "internalCommentUpdatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the internal comment is updated.", "readOnly": true }, "internalCommentUpdatedById": { "type": "string", "description": "ID of the user who updated the internal comment.", "readOnly": true } }, "required": [ "id", "uri", "path", "feedbackComponent", "createdAt", "object", "organizationId", "projectId", "status", "origin" ] }, "FeedbackList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "page": { "$ref": "#/components/schemas/Page" }, "data": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/Feedback" } } }, "required": [ "object", "page", "data" ] }, "PatchFeedbackRequest": { "type": "object", "title": "Feedback PATCH request", "minProperties": 1, "properties": { "status": { "type": "string", "description": "Feedback status.", "enum": [ "NEW", "IN_REVIEW", "RESOLVED", "ARCHIVED", "SPAM" ], "example": "ARCHIVED", "writeOnly": true }, "internalComment": { "type": [ "string", "null" ], "description": "Internal comment for the feedback.", "example": "This feedback is related to the issue 235.", "writeOnly": true } } }, "PushProjectBuildStatus": { "type": "object", "required": [ "deploy", "scorecard" ], "properties": { "deploy": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "description": "Deployment URL." }, "status": { "type": "string", "description": "Status of project deployment.", "enum": [ "pending", "running", "success", "failed", "skipped" ], "example": "running" } }, "required": [ "status", "url" ] }, "scorecard": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Scorecard name.", "example": "Scorecard: Compliance API" }, "status": { "type": "string", "enum": [ "pending", "running", "success", "failed" ] }, "description": { "type": "string", "description": "Scorecard status description." }, "url": { "type": "string", "description": "Scorecard URL." } }, "required": [ "name", "status", "description", "url" ] } } } }, "Push": { "type": "object", "required": [ "id", "remoteIds", "commit", "uploadedFiles", "isOutdated", "hasChanges", "status" ], "properties": { "id": { "description": "Push ID. Unique identifier prefixed with `push_`.", "type": "string", "pattern": "^push_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "example": "push_01h2captefvs9bpg3v6twqqj9n", "readOnly": true }, "object": { "description": "Entity name.", "type": "string", "enum": [ "push" ], "readOnly": true }, "remoteIds": { "type": "array", "items": { "type": "string", "description": "Remote IDs. Unique identifier prefixed with `rem_` for pushed remotes.", "pattern": "^rem_[0-9abcdefghjkmnpqrstvwxyz]{26}$" } }, "remoteId": { "type": "string", "description": "Remote ID. Unique identifier prefixed with `rem_` for pushed remotes. Used only for single remote push.", "pattern": "^rem_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "deprecated": true }, "commit": { "type": "object", "required": [ "message", "branchName", "author" ], "description": "Commit details.", "properties": { "message": { "type": "string", "description": "Commit message.", "example": "chore: Add new API" }, "branchName": { "type": "string", "description": "Branch name.", "example": "main" }, "sha": { "type": [ "string", "null" ], "description": "SHA of the commit.", "example": "f64ae8ea9dd7cf28822c471ea56b6d6765971305" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Commit URL.", "example": "https://gitlab.com/example-user/example-project/-/commit/f64ae8ea9dd7cf28822c471ea56b6d6765971305" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Commit creation date.", "example": "2020-01-01T00:00:00.000Z" }, "namespaceId": { "type": [ "string", "null" ], "description": "Git namespace ID (organization login for GitHub).", "example": "Redocly" }, "repositoryId": { "type": [ "string", "null" ], "description": "Git repository ID.", "example": "redoc" }, "author": { "description": "Commit author details.", "type": "object", "required": [ "email", "name" ], "properties": { "name": { "description": "Commit author name.", "example": "John Doe" }, "email": { "type": "string", "description": "Commit author email.", "format": "email", "example": "johndoe@example.com" }, "image": { "type": [ "string", "null" ], "description": "Commit author image URL.\nIf not provided, the default image is used.\nIf the image is not accessible, [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) can be used." } } }, "statuses": { "type": "array", "readOnly": true, "description": "List of commit statuses set by the platform to the commit that triggered push.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Commit status name.", "example": "Scorecard: Compliance API (org-slug/project-slug/remote-mount-path (remote))" }, "status": { "type": "string", "enum": [ "pending", "running", "success", "failed" ] }, "description": { "type": "string", "description": "Commit status description." }, "url": { "type": [ "string", "null" ], "description": "Commit status URL." } }, "required": [ "name", "status", "description", "url" ] } } } }, "scoutJobId": { "type": [ "string", "null" ], "pattern": "^job_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "`PROCESS_GIT_REPO` job, if any. Required for Scout pushes. Unique identifier prefixed with `job_`.", "example": "job_01h2captefvs9bpg3v6twqqj9n" }, "scoutJobContext": { "type": "string", "writeOnly": true, "description": "Context of the `PROCESS_GIT_REPO` job, if any.\nApplies to Scout pushes only.\nUsed as commit status context.", "example": "Team A" }, "replace": { "type": "boolean", "description": "Whether to replace the existing files.\nIf provided, all files from the remote are removed and the new files are added.\nIf not provided, the existing files are kept and the new files are added, overwriting the existing files where they overlap.", "example": true, "default": false }, "files": { "type": "object", "writeOnly": true, "description": "Map of files to upload.", "additionalProperties": { "description": "Files to push.", "type": "string", "format": "binary" } }, "uploadedFiles": { "type": "array", "readOnly": true, "description": "List of pushed files.", "items": { "type": "object", "description": "Pushed file.", "required": [ "path", "mimeType" ], "properties": { "path": { "type": "string", "description": "File path.", "example": "some-path/index.html" }, "mimeType": { "type": "string", "description": "File MIME type.", "example": "text/html" } } } }, "isMainBranch": { "type": "boolean", "example": true, "description": "Is push provided to the main branch." }, "isOutdated": { "type": "boolean", "readOnly": true, "description": "Indicates whether the push is discarded.\nIn case several pushes are performed in a row, the one with most recent commit is applied only.\nAlways `false` when commit's `createdAt` is omitted.", "example": false }, "hasChanges": { "type": "boolean", "readOnly": true, "description": "Indicates if pushed files have changes.", "example": false }, "status": { "type": "object", "readOnly": true, "description": "Status of the corresponding preview and production builds.", "required": [ "preview", "production" ], "properties": { "preview": { "$ref": "#/components/schemas/PushProjectBuildStatus" }, "production": { "$ref": "#/components/schemas/PushProjectBuildStatus" } } } } }, "PushList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "page": { "$ref": "#/components/schemas/Page" }, "data": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/Push" } } }, "required": [ "object", "page", "data" ] } }, "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "API key is required to access API.\nCreate an API key by visiting [Platform](https://app.cloud.redocly.com/) and navigating to **Access** > **API Keys** page." } }, "responses": { "BadRequestError": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalServerError": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnauthorizedError": { "description": "User is not authorized to access this resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ForbiddenError": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFoundError": { "description": "Resource not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NoContent": { "description": "No Content." }, "TooManyRequestsError": { "description": "Too Many Requests.\n\nThe organization exceeded the rate limit for this operation.\nThe `Retry-After` header gives the number of seconds to wait before the next request.", "headers": { "Retry-After": { "description": "Number of seconds to wait before sending another request.", "schema": { "type": "integer", "minimum": 1 }, "example": 30 } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": { "OrgId": { "name": "orgId", "description": "Organization ID.", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^org_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier prefixed with `org_`." }, "example": "org_01h1s5z6vf2mm1mz3hevnn9va7" }, "After": { "name": "after", "in": "query", "required": false, "description": "Cursor of the next page.\n`page.nextPage` contains it as the `after` query parameter, so you can also request `page.nextPage` directly.\nThe cursor is opaque, and its internal structure is subject to change.", "schema": { "type": "string" }, "example": "a25fgaksjf23la==" }, "Before": { "name": "before", "in": "query", "required": false, "description": "Cursor of the previous page.\n`page.previousPage` contains it as the `before` query parameter, so you can also request `page.previousPage` directly.\nThe cursor is opaque, and its internal structure is subject to change.", "schema": { "type": "string" }, "example": "bfg23aksjf23zb1==" }, "Limit": { "name": "limit", "description": "Use to return a number of results per page.\nIf there is more data, use in combination with `after` to page through the data.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "example": 10 }, "Filter": { "name": "filter", "description": "Filters the collection items. This field requires a special format.\n\nFor more information, see [Filter results](#section/filter-results).", "in": "query", "required": false, "schema": { "type": "string" }, "example": "status:approved createdAt:30d" }, "Sort": { "name": "sort", "description": "To sort by ID in descending order use `-id`.\nTo sort by ID in ascending order use `id`.", "in": "query", "required": false, "schema": { "type": "string", "default": "-id" }, "example": "-id" }, "Search": { "name": "search", "in": "query", "description": "Search.", "required": false, "schema": { "type": "string" }, "example": "text-to-search" }, "ProjectId": { "name": "projectId", "description": "Project ID.", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^prj_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier prefixed with `prj_`." }, "example": "prj_01hh1t9sa6gwfv5naz04gr7ehm" }, "ExportJobId": { "name": "exportJobId", "description": "Export Job ID.", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier prefixed with `exp_`." }, "example": "exp_01h1s5z6vf2mm1mz3hevnn9va7" }, "FeedbackId": { "name": "feedbackId", "description": "Feedback ID.", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^fb_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier prefixed with `fb_`." }, "example": "fb_01h1s5z6vf2mm1mz3hevnn9va7" }, "PushId": { "name": "pushId", "description": "Push ID.", "required": true, "in": "path", "schema": { "type": "string", "pattern": "^push_[0-9abcdefghjkmnpqrstvwxyz]{26}$", "description": "Unique identifier prefixed with `push_`." }, "example": "push_01hhh91dhc2kg9naf476y7qmas" } } } }