> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/api/readme/deploys.md). # Deploys Use these operations to interact with [deploys](/ingesting-data-into-cortex/entities-overview/entities/deploys.md) in Cortex. ### Required permissions Edit entities: Your API key must have the `Edit entities` permission. ## Operations ## GET /api/v1/catalog/{tagOrId}/deploys > List deployments for entity ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomDeployListPaginatedResponse":{"required":["deployments","page","total","totalPages"],"type":"object","properties":{"deployments":{"type":"array","items":{"$ref":"#/components/schemas/CustomDeploy1"}},"page":{"type":"integer","description":"Current page number, 0-indexed","format":"int32"},"total":{"type":"integer","description":"Total number of results","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"}}},"CustomDeploy1":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Arbitrary string-to-any map of custom data about the deploy event"},"description":"Arbitrary string-to-any map of custom data about the deploy event"},"deployer":{"$ref":"#/components/schemas/Deployer"},"deployerEmail":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"deployerName":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"environment":{"type":"string"},"sha":{"type":"string","description":"Optional commit SHA hash that this deploy corresponds to"},"timestamp":{"type":"string","description":"ISO8601 timestamp string in UTC","format":"date-time"},"title":{"type":"string","description":"Human readable title for the deploy. This is usually the commit message or PR title."},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string","description":"Optional URL associated with deployment"},"uuid":{"type":"string","format":"uuid"}}},"Deployer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/deploys":{"get":{"operationId":"getDeploysForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"description":"Number of results to return per page, between 1 and 1000. Default 250.","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32","default":250}},{"description":"Page number to return, 0-indexed. Default 0.","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDeployListPaginatedResponse"}}},"description":"Successfully retrieved deployments"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List deployments for entity","tags":["Deploys"]}}}} ``` ## POST /api/v1/catalog/{tagOrId}/deploys > Add deployment for entity ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"SaveDeployRequest":{"required":["timestamp","title","type"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object"}},"deployer":{"$ref":"#/components/schemas/Deployer"},"environment":{"type":"string"},"sha":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string"}}},"Deployer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"CustomDeploy":{"required":["serviceId","timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object"}},"deployerEmail":{"type":"string"},"deployerName":{"type":"string"},"environment":{"type":"string"},"id":{"type":"integer","format":"int64"},"serviceId":{"type":"integer","format":"int64"},"sha":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string"},"uuid":{"type":"string","format":"uuid"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/deploys":{"post":{"operationId":"addDeployForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveDeployRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDeploy"}}},"description":"Successfully created deployment"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Add deployment for entity","tags":["Deploys"]}}}} ``` ## PUT /api/v1/catalog/{tagOrId}/deploys/{uuid} > Update deployment by UUID ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"SaveDeployRequest":{"required":["timestamp","title","type"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object"}},"deployer":{"$ref":"#/components/schemas/Deployer"},"environment":{"type":"string"},"sha":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string"}}},"Deployer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"CustomDeploy":{"required":["serviceId","timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object"}},"deployerEmail":{"type":"string"},"deployerName":{"type":"string"},"environment":{"type":"string"},"id":{"type":"integer","format":"int64"},"serviceId":{"type":"integer","format":"int64"},"sha":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string"},"uuid":{"type":"string","format":"uuid"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/deploys/{uuid}":{"put":{"operationId":"updateDeployByUuid","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"path","name":"uuid","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveDeployRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDeploy"}}},"description":"Successfully updated deployment"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity or deployment not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update deployment by UUID","tags":["Deploys"]}}}} ``` ## Delete all deployments for all entities > Dangerous endpoint that blows away deploys for all entities ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"DeploysResponse":{"required":["deploys"],"type":"object","properties":{"deploys":{"type":"array","items":{"$ref":"#/components/schemas/CustomDeploy1"}}}},"CustomDeploy1":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Arbitrary string-to-any map of custom data about the deploy event"},"description":"Arbitrary string-to-any map of custom data about the deploy event"},"deployer":{"$ref":"#/components/schemas/Deployer"},"deployerEmail":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"deployerName":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"environment":{"type":"string"},"sha":{"type":"string","description":"Optional commit SHA hash that this deploy corresponds to"},"timestamp":{"type":"string","description":"ISO8601 timestamp string in UTC","format":"date-time"},"title":{"type":"string","description":"Human readable title for the deploy. This is usually the commit message or PR title."},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string","description":"Optional URL associated with deployment"},"uuid":{"type":"string","format":"uuid"}}},"Deployer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/deploys/all":{"delete":{"description":"Dangerous endpoint that blows away deploys for all entities","operationId":"deleteAllDeploys","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploysResponse"}}},"description":"Successfully deleted all deployments"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete all deployments for all entities","tags":["Deploys"]}}}} ``` ## DELETE /api/v1/catalog/{tagOrId}/deploys > Delete deployments for entity ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomDeploy":{"required":["serviceId","timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object"}},"deployerEmail":{"type":"string"},"deployerName":{"type":"string"},"environment":{"type":"string"},"id":{"type":"integer","format":"int64"},"serviceId":{"type":"integer","format":"int64"},"sha":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string"},"uuid":{"type":"string","format":"uuid"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/deploys":{"delete":{"operationId":"deleteDeploysForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"query","name":"environment","required":false,"schema":{"type":"string"}},{"in":"query","name":"sha","required":false,"schema":{"type":"string"}},{"in":"query","name":"type","required":false,"schema":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDeploy"}}},"description":"Successfully deleted deployments"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete deployments for entity","tags":["Deploys"]}}}} ``` ## DELETE /api/v1/catalog/{tagOrId}/deploys/{uuid} > Delete deployment by UUID ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomDeploy":{"required":["serviceId","timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object"}},"deployerEmail":{"type":"string"},"deployerName":{"type":"string"},"environment":{"type":"string"},"id":{"type":"integer","format":"int64"},"serviceId":{"type":"integer","format":"int64"},"sha":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"title":{"type":"string"},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string"},"uuid":{"type":"string","format":"uuid"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/{tagOrId}/deploys/{uuid}":{"delete":{"operationId":"deleteDeployByUuid","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"in":"path","name":"uuid","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDeploy"}}},"description":"Successfully deleted deployment"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity or deployment not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete deployment by UUID","tags":["Deploys"]}}}} ``` ## Delete deploys by filter > Filter and delete deploys by SHA hash, environment, or type. Note that at least one of the filters need to be set.\ > If looking to delete all deployments for an entity, use the \`Delete all deploys for entity\` endpoint instead. ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"DeploysResponse":{"required":["deploys"],"type":"object","properties":{"deploys":{"type":"array","items":{"$ref":"#/components/schemas/CustomDeploy1"}}}},"CustomDeploy1":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Arbitrary string-to-any map of custom data about the deploy event"},"description":"Arbitrary string-to-any map of custom data about the deploy event"},"deployer":{"$ref":"#/components/schemas/Deployer"},"deployerEmail":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"deployerName":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"environment":{"type":"string"},"sha":{"type":"string","description":"Optional commit SHA hash that this deploy corresponds to"},"timestamp":{"type":"string","description":"ISO8601 timestamp string in UTC","format":"date-time"},"title":{"type":"string","description":"Human readable title for the deploy. This is usually the commit message or PR title."},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string","description":"Optional URL associated with deployment"},"uuid":{"type":"string","format":"uuid"}}},"Deployer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/deploys":{"delete":{"description":"Filter and delete deploys by SHA hash, environment, or type. Note that at least one of the filters need to be set.\nIf looking to delete all deployments for an entity, use the `Delete all deploys for entity` endpoint instead.","operationId":"deleteDeploysByFilter","parameters":[{"in":"query","name":"environment","required":false,"schema":{"type":"string"}},{"in":"query","name":"sha","required":false,"schema":{"type":"string"}},{"in":"query","name":"type","required":false,"schema":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploysResponse"}}},"description":"Successfully deleted deployment"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Trying to delete deploys without any filters"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete deploys by filter","tags":["Deploys"]}}}} ``` ## GET /api/v1/deploys/environments > List all distinct deploy environments for this tenant ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"DeployEnvironmentsResponse":{"required":["environments"],"type":"object","properties":{"environments":{"type":"array","items":{"type":"string"}}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/deploys/environments":{"get":{"operationId":"listDeployEnvironments","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployEnvironmentsResponse"}}},"description":"OK"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List all distinct deploy environments for this tenant","tags":["Deploys"]}}}} ``` ## GET /api/v1/deploys/search > Search deployments across the tenant ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Deploys"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomDeployListPaginatedResponse":{"required":["deployments","page","total","totalPages"],"type":"object","properties":{"deployments":{"type":"array","items":{"$ref":"#/components/schemas/CustomDeploy1"}},"page":{"type":"integer","description":"Current page number, 0-indexed","format":"int32"},"total":{"type":"integer","description":"Total number of results","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"}}},"CustomDeploy1":{"required":["timestamp","title","type","uuid"],"type":"object","properties":{"customData":{"type":"object","additionalProperties":{"type":"object","description":"Arbitrary string-to-any map of custom data about the deploy event"},"description":"Arbitrary string-to-any map of custom data about the deploy event"},"deployer":{"$ref":"#/components/schemas/Deployer"},"deployerEmail":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"deployerName":{"type":"string","description":"Replaced with Deployer object","deprecated":true},"environment":{"type":"string"},"sha":{"type":"string","description":"Optional commit SHA hash that this deploy corresponds to"},"timestamp":{"type":"string","description":"ISO8601 timestamp string in UTC","format":"date-time"},"title":{"type":"string","description":"Human readable title for the deploy. This is usually the commit message or PR title."},"type":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]},"url":{"type":"string","description":"Optional URL associated with deployment"},"uuid":{"type":"string","format":"uuid"}}},"Deployer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/deploys/search":{"get":{"operationId":"searchDeploys","parameters":[{"description":"Filter by environment names (exact match, any of)","in":"query","name":"environments","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"description":"Filter by deploy types: DEPLOY, ROLLBACK, SCALE, RESTART","in":"query","name":"types","required":false,"schema":{"type":"array","items":{"type":"string","enum":["DEPLOY","SCALE","ROLLBACK","RESTART"]}}},{"description":"Filter to these entity tags or CIDs (any of)","in":"query","name":"entityTagOrIds","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"description":"Only deploys at or after this timestamp (ISO)","in":"query","name":"timestampAfter","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Only deploys at or before this timestamp (ISO)","in":"query","name":"timestampBefore","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Number of results to return per page, between 1 and 1000. Default 250.","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32","default":250}},{"description":"Page number to return, 0-indexed. Default 0.","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDeployListPaginatedResponse"}}},"description":"OK"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Search deployments across the tenant","tags":["Deploys"]}}}} ```