Skip to content

Profiles

CompozyOS Profiles HTTP endpoints.

For people running agent work31 pages in this section

List profiles

GET
/api/profiles

Response Body

OK

application/json
  1. response
[index: integer]?
curl -X GET "https://example.com/api/profiles"
[  {    "archived_at": "2019-08-24T14:15:22Z",    "color": "string",    "created_at": "2019-08-24T14:15:22Z",    "credential_requirements": [      {        "missing": true,        "provider": "string",        "slot": "string",        "source_extension": "string"      }    ],    "emoji": "string",    "icon": "string",    "id": "string",    "name": "string",    "needs_setup": true,    "state": "string",    "work_items": 0  }]

Create a profile

POST
/api/profiles

Request Body

JSON request body

application/json
  1. body
activate?|null
color?string
emoji?string
icon?string
name*string

Response Body

OK

application/json
  1. response
archived_at?|
Formatdate-time
color*string
created_at*string
Formatdate-time
credential_requirements?array<>
emoji*string|null
icon*string|null
id*string
name*string
needs_setup?boolean
state*string
work_items?integer
curl -X POST "https://example.com/api/profiles" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "archived_at": "2019-08-24T14:15:22Z",  "color": "string",  "created_at": "2019-08-24T14:15:22Z",  "credential_requirements": [    {      "missing": true,      "provider": "string",      "slot": "string",      "source_extension": "string"    }  ],  "emoji": "string",  "icon": "string",  "id": "string",  "name": "string",  "needs_setup": true,  "state": "string",  "work_items": 0}

List profile lifecycle operations

GET
/api/profiles/ops

Response Body

OK

application/json
  1. response
[index: integer]?
curl -X GET "https://example.com/api/profiles/ops"
[  {    "error": "string",    "id": "string",    "kind": "string",    "profile": "string",    "status": "string",    "step": "string"  }]

Retry a profile lifecycle operation

POST
/api/profiles/ops/{op_id}/retry

Path Parameters

op_id*string

Lifecycle operation id

Response Body

OK

application/json
  1. response
error?string
id*string
kind*string
profile*string
status*string
step*string
curl -X POST "https://example.com/api/profiles/ops/string/retry"
{  "error": "string",  "id": "string",  "kind": "string",  "profile": "string",  "status": "string",  "step": "string"}

Read profile selections

GET
/api/profiles/selection

Query Parameters

scope?string

Selection scope

Value in"global""workspace"
workspace_id?string

Workspace selection lens

Response Body

OK

application/json
  1. response
[index: integer]?
curl -X GET "https://example.com/api/profiles/selection"
[  {    "note": "string",    "profile": "string",    "scope": "string",    "workspace_id": "string"  }]

Remember a profile selection

PUT
/api/profiles/selection

Request Body

JSON request body

application/json
  1. body
note?string
profile*string
scope*string
workspace_id?string

Response Body

OK

application/json
  1. response
note?string
profile*string
scope*string
workspace_id?string
curl -X PUT "https://example.com/api/profiles/selection" \  -H "Content-Type: application/json" \  -d '{    "profile": "string",    "scope": "string"  }'
{  "note": "string",  "profile": "string",  "scope": "string",  "workspace_id": "string"}

Get a profile

GET
/api/profiles/{name}

Path Parameters

name*string

Profile name

Response Body

OK

application/json
  1. response
archived_at?|
Formatdate-time
color*string
created_at*string
Formatdate-time
credential_requirements?array<>
emoji*string|null
icon*string|null
id*string
name*string
needs_setup?boolean
state*string
work_items?integer
curl -X GET "https://example.com/api/profiles/string"
{  "archived_at": "2019-08-24T14:15:22Z",  "color": "string",  "created_at": "2019-08-24T14:15:22Z",  "credential_requirements": [    {      "missing": true,      "provider": "string",      "slot": "string",      "source_extension": "string"    }  ],  "emoji": "string",  "icon": "string",  "id": "string",  "name": "string",  "needs_setup": true,  "state": "string",  "work_items": 0}

Update profile identity

PATCH
/api/profiles/{name}

Path Parameters

name*string

Profile name

Request Body

JSON request body

application/json
  1. body
color?string|null
emoji?string|null
icon?string|null

Response Body

OK

application/json
  1. response
archived_at?|
Formatdate-time
color*string
created_at*string
Formatdate-time
credential_requirements?array<>
emoji*string|null
icon*string|null
id*string
name*string
needs_setup?boolean
state*string
work_items?integer
curl -X PATCH "https://example.com/api/profiles/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "archived_at": "2019-08-24T14:15:22Z",  "color": "string",  "created_at": "2019-08-24T14:15:22Z",  "credential_requirements": [    {      "missing": true,      "provider": "string",      "slot": "string",      "source_extension": "string"    }  ],  "emoji": "string",  "icon": "string",  "id": "string",  "name": "string",  "needs_setup": true,  "state": "string",  "work_items": 0}

Delete a profile

DELETE
/api/profiles/{name}

Path Parameters

name*string

Profile name

Query Parameters

plan_revision*string

Revision returned by the delete plan

Response Body

OK

application/json
  1. response
deleted*boolean
removed*
curl -X DELETE "https://example.com/api/profiles/string?plan_revision=string"
{  "deleted": true,  "removed": {    "agents": 0,    "config_keys": 0,    "credential_overrides": 0,    "desktop_partitions": 0,    "event_summaries": 0,    "loops": 0,    "mcp_servers": 0,    "palette_pins": 0,    "palette_query_hits": 0,    "palette_usage": 0,    "skills": 0,    "terminal_approvals": 0  }}

Archive a profile

POST
/api/profiles/{name}/archive

Path Parameters

name*string

Profile name

Request Body

JSON request body

application/json
  1. body
plan_revision*string

Response Body

OK

application/json
  1. response
frozen_queued_runs*integer
paused_automations*array<string>
state*string
curl -X POST "https://example.com/api/profiles/string/archive" \  -H "Content-Type: application/json" \  -d '{    "plan_revision": "string"  }'
{  "frozen_queued_runs": 0,  "paused_automations": [    "string"  ],  "state": "string"}

Preview profile archival

GET
/api/profiles/{name}/archive-plan

Path Parameters

name*string

Profile name

Response Body

OK

application/json
  1. response
approval_blockers*array<string>
automations_to_pause*array<string>
leased_runs*integer
queued_runs_to_freeze*integer
revision*string
running_sessions*array<string>
curl -X GET "https://example.com/api/profiles/string/archive-plan"
{  "approval_blockers": [    "string"  ],  "automations_to_pause": [    "string"  ],  "leased_runs": 0,  "queued_runs_to_freeze": 0,  "revision": "string",  "running_sessions": [    "string"  ]}

Preview profile deletion

GET
/api/profiles/{name}/delete-plan

Path Parameters

name*string

Profile name

Response Body

OK

application/json
  1. response
approval_blockers*array<string>
removed*
revision*string
selections_to_sweep*integer
curl -X GET "https://example.com/api/profiles/string/delete-plan"
{  "approval_blockers": [    "string"  ],  "removed": {    "agents": 0,    "config_keys": 0,    "credential_overrides": 0,    "desktop_partitions": 0,    "event_summaries": 0,    "loops": 0,    "mcp_servers": 0,    "palette_pins": 0,    "palette_query_hits": 0,    "palette_usage": 0,    "skills": 0,    "terminal_approvals": 0  },  "revision": "string",  "selections_to_sweep": 0}

Rename a profile

POST
/api/profiles/{name}/rename

Path Parameters

name*string

Profile name

Request Body

JSON request body

application/json
  1. body
new_name*string
plan_revision*string
repos?array<string>

Response Body

OK

application/json
  1. response
dormant_placements*array<>
renamed*boolean
repo_results*array<>
curl -X POST "https://example.com/api/profiles/string/rename" \  -H "Content-Type: application/json" \  -d '{    "new_name": "string",    "plan_revision": "string"  }'
{  "dormant_placements": [    {      "extension": "string",      "profile": "string",      "resource": "string"    }  ],  "renamed": true,  "repo_results": [    {      "reason": "string",      "renamed": true,      "workspace_id": "string"    }  ]}

Preview a profile rename

GET
/api/profiles/{name}/rename-plan

Path Parameters

name*string

Profile name

Query Parameters

new_name*string

New profile name

Response Body

OK

application/json
  1. response
dormant_placements*array<>
machine_folders*array<string>
repo_candidates*array<>
revision*string
vault_ref_rewrites*integer
curl -X GET "https://example.com/api/profiles/string/rename-plan?new_name=string"
{  "dormant_placements": [    {      "extension": "string",      "profile": "string",      "resource": "string"    }  ],  "machine_folders": [    "string"  ],  "repo_candidates": [    {      "path": "string",      "workspace": "string",      "workspace_id": "string"    }  ],  "revision": "string",  "vault_ref_rewrites": 0}

Unarchive a profile

POST
/api/profiles/{name}/unarchive

Path Parameters

name*string

Profile name

Request Body

JSON request body

body?unknownapplication/json

Response Body

OK

application/json
  1. response
paused_automations*array<string>
state*string
curl -X POST "https://example.com/api/profiles/string/unarchive"
{  "paused_automations": [    "string"  ],  "state": "string"}

Agents

CompozyOS Agents HTTP endpoints.

Skills

CompozyOS Skills HTTP endpoints.