> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/api-reference/reference/deployments.md).

# Deployments

Create, finalize, and resolve deployments to publish and serve project artifacts.

## Create a deployment

> Create a deployment and receive signed upload URLs for the files Argos doesn't already store. Files already present (matched by content hash) are reused and omitted from \`uploadFiles\`. The environment is inferred from the branch when omitted.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Deployments","description":"Create, finalize, and resolve deployments to publish and serve project artifacts."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer <project-token>\n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."}},"schemas":{"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"GitBranch":{"type":"string","minLength":1},"Sha256Hash":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","description":"SHA256 hash"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/deployments":{"post":{"operationId":"createDeployment","summary":"Create a deployment","description":"Create a deployment and receive signed upload URLs for the files Argos doesn't already store. Files already present (matched by content hash) are reused and omitted from `uploadFiles`. The environment is inferred from the branch when omitted.","tags":["Deployments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"description":"The branch name","$ref":"#/components/schemas/GitBranch"},"prNumber":{"description":"The pull request number","anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"environment":{"description":"The deployment environment. When omitted, it is inferred from `branch`: branches matching the configured production-branch glob are treated as `production`; all others default to `preview`.","type":"string","enum":["preview","production"]},"files":{"minItems":1,"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1},"hash":{"$ref":"#/components/schemas/Sha256Hash"},"size":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"contentType":{"type":"string","minLength":1}},"required":["path","hash","size","contentType"]},"description":"List of files to deploy"}},"required":["commit","branch","files"]}}}},"responses":{"201":{"description":"Deployment created","content":{"application/json":{"schema":{"type":"object","properties":{"deploymentId":{"type":"string"},"uploadFiles":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"hash":{"type":"string"},"uploadUrl":{"type":"string","format":"uri"}},"required":["path","hash","uploadUrl"],"additionalProperties":false}}},"required":["deploymentId","uploadFiles"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## Get a deployment

> Retrieve a single deployment by its ID.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Deployments","description":"Create, finalize, and resolve deployments to publish and serve project artifacts."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer <project-token>\n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."}},"schemas":{"GitBranch":{"type":"string","minLength":1},"Sha256Hash":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","description":"SHA256 hash"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/deployments/{deploymentId}":{"get":{"operationId":"getDeployment","summary":"Get a deployment","description":"Retrieve a single deployment by its ID.","tags":["Deployments"],"parameters":[{"in":"path","name":"deploymentId","schema":{"type":"string","description":"The deployment ID"},"required":true,"description":"The deployment ID"}],"responses":{"200":{"description":"Deployment details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","ready","error"]},"environment":{"type":"string","enum":["preview","production"]},"branch":{"$ref":"#/components/schemas/GitBranch"},"commitSha":{"$ref":"#/components/schemas/Sha256Hash"},"url":{"type":"string","format":"uri"},"createdAt":{"type":"string"}},"required":["id","status","environment","branch","commitSha","url","createdAt"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## Finalize a deployment

> Mark a deployment as ready once all of its files have been uploaded. Argos assigns the deployment's aliases and starts serving it.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Deployments","description":"Create, finalize, and resolve deployments to publish and serve project artifacts."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer <project-token>\n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."}},"schemas":{"GitBranch":{"type":"string","minLength":1},"Sha256Hash":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","description":"SHA256 hash"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/deployments/{deploymentId}/finalize":{"post":{"operationId":"finalizeDeployment","summary":"Finalize a deployment","description":"Mark a deployment as ready once all of its files have been uploaded. Argos assigns the deployment's aliases and starts serving it.","tags":["Deployments"],"parameters":[{"in":"path","name":"deploymentId","schema":{"type":"string","description":"The deployment ID"},"required":true,"description":"The deployment ID"}],"responses":{"200":{"description":"Deployment finalized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","ready","error"]},"environment":{"type":"string","enum":["preview","production"]},"branch":{"$ref":"#/components/schemas/GitBranch"},"commitSha":{"$ref":"#/components/schemas/Sha256Hash"},"url":{"type":"string","format":"uri"},"createdAt":{"type":"string"}},"required":["id","status","environment","branch","commitSha","url","createdAt"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## Resolve a deployment domain

> Resolve a deployment domain or URL to the deployment it currently serves. This endpoint is public and does not require authentication.

```json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Deployments","description":"Create, finalize, and resolve deployments to publish and serve project artifacts."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[],"paths":{"/deployments/resolve/{domain}":{"get":{"operationId":"resolveDeploymentDomain","summary":"Resolve a deployment domain","description":"Resolve a deployment domain or URL to the deployment it currently serves. This endpoint is public and does not require authentication.","tags":["Deployments"],"parameters":[{"in":"path","name":"domain","schema":{"type":"string","description":"A deployment domain or URL"},"required":true,"description":"A deployment domain or URL"}],"responses":{"200":{"description":"Deployment domain resolved","content":{"application/json":{"schema":{"type":"object","properties":{"deploymentId":{"type":"string"},"projectId":{"type":"string"},"environment":{"type":"string","enum":["preview","production"]},"visibility":{"type":"string","enum":["private","public"]}},"required":["deploymentId","projectId","environment","visibility"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://argos-ci.com/docs/api-reference/reference/deployments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.