API v1 Reference › Custom Agents

Returns all custom agents.

GEThttps://api.awork.com/api/v1/agents
GET https://api.awork.com/api/v1/agents

Lists custom agents visible to the requesting user in the current workspace, including visible global agents. Results are ordered by name and include the user's access level for each agent. Use an agent id from this response to retrieve or update its shared settings. Read GET /agents/configuration for the current user's selected accounts and connection status.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Responses

200 OK

application/json

idstringOptional
format: uuid

The id of the entity.

createdOnstringOptional
format: date-time

The date this entity was created.

createdBystringOptional
format: uuid

The id of the user who created this entity.

updatedOnstringOptional
format: date-time

The date this entity was last modified.

updatedBystringOptional
format: uuid

The id of the user who last modified this entity.

isOfficialbooleanOptional

Whether a workspace admin marked this item as official. False when metadata is disabled.

tagsarray of object or nullOptional

The canonical AI tags. Empty when metadata is disabled.

Show 4 properties
idstringOptional
format: uuid

The stable identifier of this workspace tag.

namestring or nullOptional

The shared display name.

colorstring or nullOptional

The shared display color.

assignmentCountinteger or nullOptional
format: int32

The number of active agents, skills, and connectors that use this tag. Only set by the tag list.

canEditTagsbooleanOptional

Whether the current viewer can replace this item's tags.

canSetOfficialbooleanOptional

Whether the current viewer can change this item's official status.

typestring or nullOptional

The public agent type.

connectorsarray of object or nullOptional

The linked connectors.

Show 5 properties
idstringOptional
format: uuid

The linked connector identifier.

namestring or nullOptional

The connector name.

statusstring or nullOptional

Always pending in this shared response. It does not indicate whether an account is connected. Read the agent's configuration endpoint for the current user's connection status.

connectionModestring or nullOptional

How the agent chooses an account: actingUser lets each user supply their own; specificConnection uses the editor-provided account for everyone.

connectionIdstring or nullOptional
format: uuid

The editor-provided account id in specificConnection mode; otherwise null.

namestring or nullOptional

The name shown to users.

descriptionstring or nullOptional

A short explanation of what the agent does.

currentSystemPromptVersionIdstring or nullOptional
format: uuid

The current system prompt version.

modelProviderstring or nullOptional

The configured model provider when no preset is selected.

modelNamestring or nullOptional

The configured model name when no preset is selected.

presetKeystring or nullOptional

The configured workspace model preset key.

reasoningLevelstring or nullOptional

The configured reasoning level.

systemPromptstring or nullOptional

The current system prompt.

webSearchEnabledbooleanOptional

Whether web search is enabled.

aworkAccessEnabledbooleanOptional

Whether awork access is enabled.

googleGenAiAccessEnabledbooleanOptional

Whether Google image generation is enabled.

openAiImageGenerationAccessEnabledbooleanOptional

Whether OpenAI image generation is enabled.

skillIdsarray of string or nullOptional

The skills linked to the agent.

hasImagebooleanOptional

Whether the agent has a profile image.

isArchivedbooleanOptional

Whether the agent is archived.

workspaceAccessLevelstring or nullOptional

Allowed: "read" "manage"

The workspace-wide access level.

hasAdminAccessOnlybooleanOptional

Whether the agent is visible only through workspace administration access.

accessLevelstringOptional

Allowed: "read" "manage"

The requesting user's access level.

Search documentation