Agentuity Documentation

Full project lifecycle management including deployments, agents, environment variables, and hostnames.

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Project Management

Create Project

Create a new project within an organization.

POST/cli/project

https://catalyst-usw.agentuity.cloud/cli/project

Request Body

Project creation payload.

Field	Type	Description
`name`	string	the name of the new project
`description`	string	the description of the project (optional)
`tags`	string[]	tags for the project (optional)
`orgId`	string	the organization id to create the project in
`cloudRegion`	string	the cloud region to create the project
`domains`	string[]	the custom domains for this project (optional)

Response

Returns the created project ID and SDK key.

Status	Description
201	Project created
401	Unauthorized — invalid or missing API key

Response Fields

Field	Type	Description
`id`	string	the unique id for the project
`sdkKey`	string	the SDK key for the project

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/cli/project' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-project",
  "orgId": "org_abc123",
  "cloudRegion": "usw"
}'

List Projects

List all projects accessible to the authenticated user.

GET/cli/project

https://catalyst-usw.agentuity.cloud/cli/project

Parameters

query

Name	Type	Required	Description
`hasDeployment`	boolean	No	Filter to projects with deployments
`limit`	number	No	Max results (default 1000, max 10000)

Response

Returns a list of projects.

Status	Description
200	Projects returned
401	Unauthorized — invalid or missing API key

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Project

Retrieve a specific project by ID. The mask and includeProjectKeys query parameters both default to true when omitted.

GET/cli/project/{id}

https://catalyst-usw.agentuity.cloud/cli/project/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Project ID

query

Name	Type	Required	Description
`mask`	boolean	No	Mask secrets (default true)
`includeProjectKeys`	boolean	No	Include SDK keys (default true)

Response

Returns the project details.

Status	Description
200	Project returned
401	Unauthorized — invalid or missing API key
404	Project not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Projects

Delete one or more projects by ID.

DELETE/cli/project

https://catalyst-usw.agentuity.cloud/cli/project

Request Body

Project deletion payload.

Field	Type	Description
`ids`	string[]	Array of project IDs to delete.

Response

Returns array of deleted project IDs.

Status	Description
200	Projects deleted
401	Unauthorized — invalid or missing API key

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/cli/project' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "ids": [
    "proj_abc123"
  ]
}'

Check Project Exists

Check if a project with the given name already exists.

GET/cli/project/exists/{name}

https://catalyst-usw.agentuity.cloud/cli/project/exists/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Project name (URL-encoded)

query

Name	Type	Required	Description
`orgId`	string	Yes	Organization ID

Response

Returns true (HTTP 409) if exists, false (HTTP 422) if not.

Status	Description
409	Project exists
422	Project does not exist
401	Unauthorized — invalid or missing API key

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project/exists/my-project?orgId=org_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Project Region

Update the cloud region for a project.

PATCH/cli/project/{id}

https://catalyst-usw.agentuity.cloud/cli/project/{id}

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Project ID

Request Body

Region update payload.

Field	Type	Description
`cloudRegion`	string	the cloud region to update the project to

Response

Returns the updated project.

Status	Description
200	Project updated
401	Unauthorized — invalid or missing API key
404	Project not found

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "cloudRegion": "use"
}'

Environment Variables

Update Env Variables

Update environment variables and secrets for a project.

PUT/cli/project/{id}/env

https://catalyst-usw.agentuity.cloud/cli/project/{id}/env

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Project ID

Request Body

Environment variable update payload.

Field	Type	Description
`env`	object	environment variables to set/update (optional)
`secrets`	object	secrets to set/update (optional)

Response

Returns the updated environment variables.

Status	Description
200	Environment variables updated
401	Unauthorized — invalid or missing API key
404	Project not found

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/env' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "env": {
    "DB_HOST": "localhost"
  },
  "secrets": {
    "DB_PASS": "secret"
  }
}'

Delete Env Variables

Delete specific environment variables and secrets from a project.

DELETE/cli/project/{id}/env

https://catalyst-usw.agentuity.cloud/cli/project/{id}/env

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Project ID

Request Body

Environment variable deletion payload.

Field	Type	Description
`env`	string[]	environment variable keys to delete (optional)
`secrets`	string[]	secret keys to delete (optional)

Response

Empty response on success.

Status	Description
204	Environment variables deleted
401	Unauthorized — invalid or missing API key
404	Project not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/env' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "env": [
    "OLD_VAR"
  ],
  "secrets": [
    "OLD_SECRET"
  ]
}'

Agents

List Agents

List agents for a project.

GET/cli/agent/{projectId}

https://catalyst-usw.agentuity.cloud/cli/agent/{projectId}

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID

query

Name	Type	Required	Description
`deploymentId`	string	No	Filter by deployment ID
`orgId`	string	No	Filter by organization ID

Response

Returns a list of agents for the project.

Status	Description
200	Agents returned
401	Unauthorized — invalid or missing API key
404	Project not found

Response Fields

Field	Type	Description
`id`	string	Agent ID (same as identifier)
`name`	string	Agent name
`description`	string \| null	Agent description
`identifier`	string	Agent identifier
`deploymentId`	string \| null	Deployment ID
`devmode`	boolean	Whether agent is in development mode
`metadata`	object \| null	Agent metadata
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp
`evals`	object[]	Associated evaluations
`evals[].id`	string	Evaluation ID
`evals[].name`	string	Evaluation name
`evals[].description`	string \| null	Evaluation description
`evals[].identifier`	string \| null	Evaluation identifier
`evals[].devmode`	boolean	Whether evaluation is in development mode
`evals[].createdAt`	string	Creation timestamp
`evals[].updatedAt`	string	Last update timestamp

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/agent/proj_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Agent by Identifier

Retrieve a specific agent by its identifier.

GET/cli/agent/{projectId}

https://catalyst-usw.agentuity.cloud/cli/agent/{projectId}

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID

query

Name	Type	Required	Description
`identifier`	string	Yes	Agent identifier

Response

Returns the agent matching the identifier.

Status	Description
200	Agent returned
401	Unauthorized — invalid or missing API key
404	Agent not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/agent/proj_abc123?identifier=my-agent' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Deployments

List Deployments

List deployments for a project.

GET/cli/project/{projectId}/deployments

https://catalyst-usw.agentuity.cloud/cli/project/{projectId}/deployments

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID

query

Name	Type	Required	Description
`limit`	number	No	Max results (default 10)
`orgId`	string	No	Filter by organization ID

Response

Returns a list of deployments for the project.

Status	Description
200	Deployments returned
401	Unauthorized — invalid or missing API key
404	Project not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/deployments' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Deployment

Retrieve a specific deployment by ID.

GET/cli/project/{projectId}/deployments/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/project/{projectId}/deployments/{deploymentId}

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID
`deploymentId`	string	Yes	Deployment ID

Response

Returns the deployment details.

Status	Description
200	Deployment returned
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/deployments/dep_def456' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Deployment

Delete a specific deployment.

DELETE/cli/project/{projectId}/deployments/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/project/{projectId}/deployments/{deploymentId}

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID
`deploymentId`	string	Yes	Deployment ID

Response

Returns confirmation of deletion.

Status	Description
200	Deployment deleted
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/deployments/dep_def456' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Rollback Deployment

Rollback to a specific deployment version.

POST/cli/project/{projectId}/deployments/{deploymentId}/rollback

https://catalyst-usw.agentuity.cloud/cli/project/{projectId}/deployments/{deploymentId}/rollback

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID
`deploymentId`	string	Yes	Deployment ID

Response

Rolls back to the specified deployment version.

Status	Description
200	Rollback initiated
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/deployments/dep_def456/rollback' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Undeploy Project

Undeploy all active deployments for a project.

POST/cli/project/{projectId}/deployments/undeploy

https://catalyst-usw.agentuity.cloud/cli/project/{projectId}/deployments/undeploy

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID

Response

Returns confirmation of undeployment.

Status	Description
200	Project undeployed
401	Unauthorized — invalid or missing API key
404	Project not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/deployments/undeploy' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Deployment Logs

Retrieve logs for a specific deployment.

GET/cli/project/{projectId}/deployments/{deploymentId}/logs

https://catalyst-usw.agentuity.cloud/cli/project/{projectId}/deployments/{deploymentId}/logs

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID
`deploymentId`	string	Yes	Deployment ID

query

Name	Type	Required	Description
`limit`	number	No	Max results (default 100)

Response

Returns deployment log entries.

Status	Description
200	Logs returned
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/deployments/dep_def456/logs' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Deployment Info

Lightweight deployment lookup — returns ID, project, org, region, state, and active status.

GET/cli/deployment/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/deployment/{deploymentId}

Parameters

path

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID

Response

Lightweight deployment lookup — returns ID, project, org, region, state, and active status.

Status	Description
200	Deployment info returned
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/deployment/dep_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Deploy Pipeline

Start Deployment

Start a new deployment for a project.

POST/cli/deploy/2/start/{projectId}

https://catalyst-usw.agentuity.cloud/cli/deploy/2/start/{projectId}

Parameters

path

Name	Type	Required	Description
`projectId`	string	Yes	Project ID

Request Body

Deployment configuration payload.

Field	Type	Description
`resources`	object	the resource requirements for your deployed project (optional)
`resources.memory`	string	The memory requirements
`resources.cpu`	string	The CPU requirements
`resources.disk`	string	The disk requirements
`mode`	object	the provisioning mode for the project (optional)
`mode.type`	string	on-demand or provisioned
`mode.idle`	string	duration in seconds if on-demand (optional)
`dependencies`	string[]	(optional)
`domains`	string[]	(optional)

Response

Returns deployment details and upload information.

Status	Description
201	Deployment started
401	Unauthorized — invalid or missing API key
404	Project not found

Response Fields

Field	Type	Description
`id`	string	the unique id for the deployment
`orgId`	string	the organization id
`publicKey`	string	the public key to use for encrypting the deployment
`buildLogsStreamURL`	string	the URL for streaming build logs (PUT to write, GET to read)

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/cli/deploy/2/start/proj_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "resources": {
    "memory": 512,
    "cpu": 1
  }
}'

Upload Build Metadata

Upload build metadata for a deployment in progress.

PUT/cli/deploy/2/start/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/deploy/2/start/{deploymentId}

Parameters

path

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID

Response

Returns pre-signed upload URLs for the deployment archive and assets.

Status	Description
200	Upload URLs returned
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/cli/deploy/2/start/dep_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Complete Deployment

Signal that a deployment upload is complete and ready for activation.

POST/cli/deploy/2/complete/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/deploy/2/complete/{deploymentId}

Parameters

path

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID

Response

Returns warmup stream and public URL information.

Status	Description
200	Deployment completed
401	Unauthorized — invalid or missing API key
404	Deployment not found

Response Fields

Field	Type	Description
`streamId`	string	the stream id for warmup logs (optional)
`publicUrls`	object	the map of public urls
`publicUrls.latest`	string	the public url for the latest deployment
`publicUrls.deployment`	string	the public url for this deployment
`publicUrls.custom`	string[]
`publicUrls.vanityDeployment`	string \| null	the vanity url for this deployment (optional)
`publicUrls.vanityProject`	string \| null	the vanity url for the latest deployment (optional)

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/cli/deploy/2/complete/dep_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Deploy Status

Check the current status of a deployment.

GET/cli/deploy/2/status/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/deploy/2/status/{deploymentId}

Parameters

path

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID

Response

Returns the current deployment state.

Status	Description
200	Status returned
401	Unauthorized — invalid or missing API key
404	Deployment not found

Response Fields

Field	Type	Description
`state`	string	the current deployment state

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/deploy/2/status/dep_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Report Deploy Failure

Report a deployment failure with error details.

POST/cli/deploy/2/fail/{deploymentId}

https://catalyst-usw.agentuity.cloud/cli/deploy/2/fail/{deploymentId}

Parameters

path

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID

Request Body

Failure report payload.

Field	Type	Description
`error`	string	(optional)
`diagnostics`	object	(optional)
`diagnostics.success`	boolean
`diagnostics.errors`	object[]
`diagnostics.errors[].type`	string
`diagnostics.errors[].scope`	string
`diagnostics.errors[].path`	string	(optional)
`diagnostics.errors[].line`	number	(optional)
`diagnostics.errors[].column`	number	(optional)
`diagnostics.errors[].message`	string
`diagnostics.errors[].code`	string	(optional)
`diagnostics.warnings`	object[]
`diagnostics.warnings[].type`	string
`diagnostics.warnings[].scope`	string
`diagnostics.warnings[].path`	string	(optional)
`diagnostics.warnings[].line`	number	(optional)
`diagnostics.warnings[].column`	number	(optional)
`diagnostics.warnings[].message`	string
`diagnostics.warnings[].code`	string	(optional)
`diagnostics.diagnostics`	object[]
`diagnostics.diagnostics[].name`	string
`diagnostics.diagnostics[].startedAt`	string
`diagnostics.diagnostics[].completedAt`	string
`diagnostics.diagnostics[].durationMs`	number
`diagnostics.error`	string	(optional)

Response

Returns confirmation of failure report.

Status	Description
200	Failure reported
401	Unauthorized — invalid or missing API key
404	Deployment not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/cli/deploy/2/fail/dep_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "error": "Build failed: TypeScript compilation error"
}'

Hostname

Get Hostname

Get the vanity hostname for a project.

GET/cli/project/{id}/hostname

https://catalyst-usw.agentuity.cloud/cli/project/{id}/hostname

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Project ID

Response

Returns the vanity hostname and URL.

Status	Description
200	Hostname returned
401	Unauthorized — invalid or missing API key
404	Project not found

Response Fields

Field	Type	Description
`hostname`	string \| null	The vanity hostname for the project, or null if not set.
`url`	string \| null	The full URL for the project hostname, or null if not set.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/hostname' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Set Hostname

Set a vanity hostname for a project.

PUT/cli/project/{id}/hostname

https://catalyst-usw.agentuity.cloud/cli/project/{id}/hostname

Parameters

path

Name	Type	Required	Description
`id`	string	Yes	Project ID

Request Body

Hostname configuration payload.

Field	Type	Description
`projectId`	string	the project id
`hostname`	string	the vanity hostname to set

Response

Returns the configured hostname and URL.

Status	Description
200	Hostname set
401	Unauthorized — invalid or missing API key
404	Project not found

Response Fields

Field	Type	Description
`hostname`	string	The vanity hostname that was set.
`url`	string	The full URL for the project hostname.

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/cli/project/proj_abc123/hostname' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "hostname": "my-app"
}'

Security

Check for Malware

Scan deployment dependencies for known malware.

POST/security/{deploymentId}/malware-check

https://catalyst-usw.agentuity.cloud/security/{deploymentId}/malware-check

Parameters

path

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID (URL-encoded)

Request Body

Malware scan payload.

Field	Type	Description
`ecosystem`	string	Package ecosystem (e.g., `npm`)
`packages`	object[]	Array of packages to scan, each with name and version
`packages[].name`	string	Package name (e.g., lodash, express)
`packages[].version`	string	Package version (e.g., 4.17.21)

Response

Returns scan results. If action is 'block', the deployment should be blocked.

Status	Description
200	Scan completed
401	Unauthorized — invalid or missing API key

Response Fields

Field	Type	Description
`action`	string	Action to take based on the scan results (allow or block deployment).
`summary`	object	Summary of the malware check scan.
`summary.scanned`	number	Total number of packages scanned.
`summary.flagged`	number	Number of packages flagged as potentially malicious.
`findings`	object[]	List of malware detection findings.
`findings[].name`	string	Name of the flagged package.
`findings[].version`	string	Version of the flagged package.
`findings[].reason`	string	Reason why the package was flagged as potentially malicious.
`list`	object	Metadata about the malware list used, if available.
`list.fetchedAt`	string	ISO 8601 timestamp when the malware list was last fetched.
`list.count`	number	Number of entries in the malware list.
`error`	string	Error message if the malware check encountered an issue.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/security/dep_abc123/malware-check' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "ecosystem": "npm",
  "packages": [
    {
      "name": "lodash",
      "version": "4.17.21"
    }
  ]
}'