> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deny a tool call

> Refuse an action the agent wanted to take, and tell it why. The memo is the whole feature.

A tool behind [approval](/docs/api-reference/objectiveservice/approve-a-tool-call) parks at `TOOL_CALL_STATUS_WAITING_FOR_APPROVAL` and the objective waits. Denying it tells the agent the action is off the table.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.objectives.toolCalls.deny(toolCallId, {
    workspaceId,
    objectiveId,
    memo: 'Do not invent company names. Ask the user for the real one.',
  });
  ```

  ```go Go theme={null}
  _, err := client.Objectives.ToolCalls.Deny(ctx, objectiveID, toolCallID,
  	cadenya.ObjectiveToolCallDenyParams{
  		WorkspaceID: cadenya.String(workspaceID),
  		Memo:        cadenya.String("Do not invent company names. Ask the user for the real one."),
  	})
  ```

  ```ruby Ruby theme={null}
  cadenya.objectives.tool_calls.deny(
    tool_call_id,
    workspace_id: workspace_id,
    objective_id: objective_id,
    memo: "Do not invent company names. Ask the user for the real one."
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/tool_calls/${TOOL_CALL_ID}:deny" \
    -H "Authorization: Bearer ${CADENYA_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"memo": "Do not invent company names. Ask the user for the real one."}'
  ```
</CodeGroup>

The tool never runs. The agent keeps working.

## The memo is the difference between a wall and a hint

Deny with no memo and the agent knows only that it may not do that. It shrugs and tries something else:

```
deny {}
→ toolDenied  { toolCallId: 'toolcall_01KX1QTA...', memo: '' }
→ assistant:  "Let me check what fake data generators are available:"
```

Deny with a memo and the agent reads it, in the same run:

```
deny { memo: 'Do not invent company names. Ask the user for the real one.' }
→ toolDenied  { toolCallId: 'toolcall_01KX1QRH...', memo: 'Do not invent company names. ...' }
→ assistant:  "I apologize, but I'm unable to generate fake company names.
               I can only generate fake data for Acme's legitimate..."
```

Both are real runs of the same agent on the same message. The memo is the steering wheel: it lands in the agent's context as the reason, so it can pick a different approach rather than guess at your policy.

Write the memo as an instruction to the agent, not a note to your audit log. "Refund exceeds the \$500 limit; escalate to a human instead" gives the agent somewhere to go. "Denied" does not.

## The response reports the state before the decision

Denial resolves asynchronously, and the response body carries almost nothing:

```typescript theme={null}
const response = await client.objectives.toolCalls.deny(toolCallId, { workspaceId, objectiveId });

response.status;           // 'TOOL_CALL_STATUS_UNSPECIFIED'
response.executionStatus;  // 'TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED'
```

Read the call back for the settled state:

```typescript theme={null}
const settled = await client.objectives.toolCalls.retrieve(toolCallId, { workspaceId, objectiveId });

settled.status;           // 'TOOL_CALL_STATUS_DENIED'
settled.executionStatus;  // 'TOOL_CALL_EXECUTION_STATUS_PENDING'  ← it never ran
settled.data.memo;        // the memo you sent
settled.data.statusChangedBy;  // the profile that decided
```

`executionStatus` stays `PENDING` forever. That is the tell: a denied call is one that was never executed, not one that failed.

## Deciding twice

A tool call can be decided once. A second decision, in either direction, comes back `404`:

```
POST .../tool_calls/{id}:deny     → 200
POST .../tool_calls/{id}:deny     → 404  "tool call ... is not pending approval"
POST .../tool_calls/{id}:approve  → 404  "tool call ... is not pending approval"
```

<Warning>
  That `404` does not mean the tool call is missing. It means someone already decided, or the objective moved on. The message says so; the status code does not.

  An approval queue with two reviewers hits this on day one. Treat a `404` on `:deny` as "refresh and show the outcome", not as "this does not exist."
</Warning>

## Finding the calls waiting on you

```typescript theme={null}
const parked = await client.objectives.toolCalls.list(objectiveId, {
  workspaceId,
  status: 'TOOL_CALL_STATUS_WAITING_FOR_APPROVAL',
});

for await (const call of parked) {
  if (call.data.callable.type !== 'tool') continue;
  console.log(call.data.callable.tool.name, call.data.arguments);
  // GenerateFake { name: 'company' }
}
```

The `toolApprovalRequested` event fires on the [stream](/docs/api-reference/objectiveeventstreamsservice/stream-objective-events) the moment a call parks, so a UI does not have to poll. `toolDenied` fires when you decide, carrying the `toolCallId` and the `memo`.

## Putting a tool behind approval

Approval is a property of the tool, and a synced tool set does not let you edit its tools:

```
PATCH .../tools/{id}  { spec: { requiresApproval: true } }
→ 400  "tools on a synced source (MCP or OpenAPI URL) are managed automatically
        and cannot be created, edited, or deleted directly"
```

Set it on the adapter instead, and every synced tool inherits it:

```typescript theme={null}
await client.toolSets.update(toolSetId, {
  workspaceId,
  spec: {
    adapter: {
      type: 'mcp',
      mcp: {
        url: 'https://free.cadenya.com/faker-mcp',
        toolApprovals: { type: 'always', always: true },
      },
    },
  },
});
```

Use an `only` filter in `toolApprovals` to gate a subset. For [bare and HTTP tools](/docs/api-reference/toolservice/create-a-new-tool-set), which you define by hand, set `requiresApproval` on the tool directly.

## Related

<CardGroup cols={2}>
  <Card title="Approve a tool call" icon="check" href="/docs/api-reference/objectiveservice/approve-a-tool-call">
    The other decision, and the same `404` on a second one.
  </Card>

  <Card title="List tool calls" icon="list-check" href="/docs/api-reference/objectiveservice/list-objective-tool-calls">
    Filter by `WAITING_FOR_APPROVAL` to build the queue.
  </Card>

  <Card title="Create a tool set" icon="wrench" href="/docs/api-reference/toolservice/create-a-new-tool-set">
    `toolApprovals`, and why synced tools reject edits.
  </Card>

  <Card title="Set tool call content" icon="reply" href="/docs/api-reference/objectiveservice/set-a-bare-tool-calls-content">
    When you want the human to *be* the tool, not only gate it.
  </Card>
</CardGroup>


## OpenAPI

````yaml post /v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}:deny
openapi: 3.1.0
info:
  title: Cadenya API
  description: API for the Cadenya Agent Runtime platform.
  version: '1.0'
servers:
  - url: https://api.cadenya.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: AIProviderKeyService
  - name: APIKeyService
    description: |-
      Issue, rotate, disable, and revoke a workspace's API keys. Every key
       belongs to exactly one workspace; the system-managed global account key is
       managed via GlobalAPIKeyService instead.
  - name: AccountService
    description: >-
      Manage the authenticated account. Accounts are the top-level
      organizational
       unit and contain one or more workspaces.
  - name: AgentScheduleService
    description: >-
      Manage recurring schedules attached to agents. Schedules trigger
      objectives
       on a cadence defined by AgentScheduleSpec.Schedule.
  - name: AgentService
    description: >-
      Manage AI agents within a workspace. Agents define AI behavior and tool
      access.
  - name: AgentVariationService
    description: >-
      Manage variations of an agent and their tool, sub-agent, and memory layer
      assignments.
  - name: GlobalAPIKeyService
    description: |-
      Manage the account's system-provisioned global API key. The global key is
       the only key that spans every workspace; it is created by the system and
       cannot be deleted, so the surface is retrieve, rotate, and the
       disable/enable kill switch.
  - name: MemoryService
    description: >-
      Manage memory layers and their entries. Layers are named containers that
      can
       be composed into an objective's memory cascade; entries are the keyed values
       within a layer. System-managed layers (e.g., episodic layers created by the
       runtime) cannot be mutated through this API.
  - name: ModelService
    description: |-
      Manage LLM models available to a workspace. Models represent provider and
       family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
       with the supported models and you can enable or disable each one.
  - name: ObjectiveEventStreamsService
  - name: ObjectiveService
  - name: ProfilesService
    description: |-
      Operations on profiles, the account-level principals (users, API keys,
       system) that authenticate against the API.
  - name: SearchService
  - name: TenantService
    description: >-
      Read and erase tenants and the subjects under them. Tenants and subjects
      are
       created by assertion — on objective creation or widget session mint — never
       directly, so this service has no create or update: it exists to enumerate what
       assertions have produced, and to destroy it on request.
  - name: ToolService
    description: >-
      Manage tool sets and the tools they contain. Tool sets group related
      tools,
       and tools define specific capabilities available to agents.

       When a tool set is managed, only API key actors can modify its tools; human
       (profile) actors cannot.
  - name: UploadService
    description: |-
      Issue short-lived presigned URLs for direct client-to-object-storage
       uploads. Created uploads can be referenced by id when creating or updating
       resources that accept binary content (e.g., MemoryEntry).
  - name: WidgetService
    description: |-
      Manage embeddable chat widgets. A widget binds an agent to a globally
       unique hostname with a per-widget origin allowlist; browsers reach it with
       session tokens minted via WidgetSessionService.
  - name: WidgetSessionService
    description: >-
      Mint and manage widget sessions. Session creation is server-to-server
      only:
       the customer's backend authenticates its visitor, asserts tenant/subject
       context, attaches any per-visitor secrets, and receives a short-lived
       bearer token the browser uses against the widget host.
  - name: WorkspaceAdminService
    description: >-
      Administer workspaces across the account: create and archive workspaces
      and
       manage their membership. These operations are account-scoped and require the
       admin role (a token whose profile holds the WorkOS admin role); they live
       under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
       tree so an admin can manage any workspace in the account, including ones they
       are not themselves a member of.
  - name: WorkspaceSecretService
  - name: WorkspaceService
    description: |-
      Manage workspaces within an account. Workspaces provide organizational
       grouping and isolation for resources such as agents, tools, and API keys.

       This is the workspace-scoped, end-user surface. Administrative operations
       (create / archive workspaces, manage members) live in WorkspaceAdminService
       under /v1/account/workspaces and require the admin role.
paths:
  /v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}:deny:
    post:
      tags:
        - ObjectiveService
        - Objectives
      summary: Deny a tool call
      description: >-
        When an agent attempts to use a tool that requires approval, use this
        endpoint to mark it as denied. Use a memo to steer the LLM to a
        different decision or usage of the tool.
      operationId: ObjectiveService_DenyToolCall
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
            example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
        - name: objectiveId
          in: path
          description: >-
            The ID of the objective. Supports "external_id:" prefix for external
            IDs.
          required: true
          schema:
            example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
            type: string
        - name: toolCallId
          in: path
          description: The ID of the tool call to deny
          required: true
          schema:
            example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DenyToolCallRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectiveToolCall'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Cadenya from '@cadenya/cadenya';

            const client = new Cadenya({
              apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
            });

            const objectiveToolCall = await client.objectives.toolCalls.deny(
              'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
              'toolcall_01HXKD2E5NQM3T9AYWCFTANFGV',
              { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
            );

            console.log(objectiveToolCall.data);
        - lang: Python
          source: |-
            import os
            from cadenya import Cadenya

            client = Cadenya(
                api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
            )
            objective_tool_call = client.objectives.tool_calls.deny(
                objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
                tool_call_id="toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
                workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
            )
            print(objective_tool_call.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tobjectiveToolCall, err := client.Objectives.ToolCalls.Deny(\n\t\tcontext.TODO(),\n\t\t\"obj_01HXKD2E5NQM3T9AYWCFQAZGFV\",\n\t\t\"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV\",\n\t\tcadenya.ObjectiveToolCallDenyParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", objectiveToolCall.Data)\n}\n"
        - lang: Ruby
          source: |-
            require "cadenya"

            cadenya = Cadenya::Client.new(api_key: "My API Key")

            objective_tool_call = cadenya.objectives.tool_calls.deny(
              "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
              "toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
              workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
            )

            puts(objective_tool_call)
        - lang: CLI
          source: |-
            cadenya objectives:tool-calls deny \
              --api-key 'My API Key' \
              --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
              --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
              --tool-call-id toolcall_01HXKD2E5NQM3T9AYWCFTANFGV
components:
  schemas:
    DenyToolCallRequest:
      type: object
      properties:
        workspaceId:
          readOnly: true
          example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
          type: string
        objectiveId:
          readOnly: true
          example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
          type: string
          description: >-
            The ID of the objective. Supports "external_id:" prefix for external
            IDs.
        toolCallId:
          readOnly: true
          example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV
          type: string
          description: The ID of the tool call to deny
        memo:
          type: string
          description: >-
            A memo to associate to the tool call denial. Use a memo to steer the
            LLM to a different decision or usage of the tool.
    ObjectiveToolCall:
      required:
        - metadata
        - data
        - status
        - executionStatus
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/OperationMetadata'
        data:
          $ref: '#/components/schemas/ObjectiveToolCallData'
        status:
          enum:
            - TOOL_CALL_STATUS_UNSPECIFIED
            - TOOL_CALL_STATUS_AUTO_APPROVED
            - TOOL_CALL_STATUS_WAITING_FOR_APPROVAL
            - TOOL_CALL_STATUS_APPROVED
            - TOOL_CALL_STATUS_DENIED
          type: string
          description: Current status of the tool call
          format: enum
        info:
          $ref: '#/components/schemas/ObjectiveToolCallInfo'
        executionStatus:
          readOnly: true
          enum:
            - TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED
            - TOOL_CALL_EXECUTION_STATUS_PENDING
            - TOOL_CALL_EXECUTION_STATUS_RUNNING
            - TOOL_CALL_EXECUTION_STATUS_COMPLETED
            - TOOL_CALL_EXECUTION_STATUS_ERRORED
            - TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT
          type: string
          format: enum
      description: >-
        ObjectiveToolCall is a record of a tool call made during an objective's
        execution.
         Tool calls are mutable — their status changes as they are approved, denied, or executed.
    Status:
      type: object
      properties:
        code:
          type: integer
          description: >-
            The status code, which should be an enum value of
            [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: >-
            A developer-facing error message, which should be in English. Any
            user-facing error message should be localized and sent in the
            [google.rpc.Status.details][google.rpc.Status.details] field, or
            localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: >-
            A list of messages that carry the error details.  There is a common
            set of message types for APIs to use.
      description: >-
        The `Status` type defines a logical error model that is suitable for
        different programming environments, including REST APIs and RPC APIs. It
        is used by [gRPC](https://github.com/grpc). Each `Status` message
        contains three pieces of data: error code, error message, and error
        details. You can find out more about this error model and how to work
        with it in the [API Design
        Guide](https://cloud.google.com/apis/design/errors).
    OperationMetadata:
      required:
        - id
        - accountId
        - workspaceId
        - profileId
        - createdAt
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: >-
            Unique identifier for the operation (prefixed ULID, e.g.,
            "obj_01HXK...")
        accountId:
          readOnly: true
          example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
          type: string
          description: >-
            Account this operation belongs to for multi-tenant isolation
            (prefixed ULID)
        workspaceId:
          readOnly: true
          example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
          type: string
          description: >-
            Workspace this operation belongs to for organizational grouping
            (prefixed ULID)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}
        createdAt:
          readOnly: true
          type: string
          description: |-
            Timestamp when this operation was created
             ULID includes timestamp information, but this explicit field enables easier querying
          format: date-time
        externalId:
          type: string
          description: >-
            External ID for the operation (e.g., a workflow ID from an external
            system)
        profileId:
          readOnly: true
          example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
          type: string
          description: >-
            ID of the actor (user or service account) that created this
            operation
      description: >-
        Metadata for ephemeral operations and activities (e.g., objectives,
        executions, runs)
    ObjectiveToolCallData:
      required:
        - callable
      type: object
      properties:
        callable:
          allOf:
            - $ref: '#/components/schemas/CallableTool'
          description: The tool that was called
        arguments:
          type: object
          additionalProperties: true
          description: The arguments passed to the tool
        memo:
          type: string
          description: A memo supplied by the reviewer when denying the tool call
        statusChangedBy:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/Profile'
          description: >-
            The profile that changed the status of this tool call. Set when the
            status is changed to APPROVED or DENIED by a user.
        resolvedSecrets:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/ResolvedSecret'
          description: List of resolved secrets used by the tool call
    ObjectiveToolCallInfo:
      type: object
      properties:
        objective:
          $ref: '#/components/schemas/OperationMetadata'
        createdBy:
          $ref: '#/components/schemas/Profile'
        tool:
          $ref: '#/components/schemas/BareMetadata'
        toolSet:
          $ref: '#/components/schemas/BareMetadata'
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: >-
        Contains an arbitrary serialized message along with a @type that
        describes the type of the serialized message.
    CallableTool:
      oneOf:
        - $ref: '#/components/schemas/CallableTool_Tool'
        - $ref: '#/components/schemas/CallableTool_Agent'
        - $ref: '#/components/schemas/CallableTool_CadenyaProvidedTool'
      discriminator:
        propertyName: type
        mapping:
          tool:
            $ref: '#/components/schemas/CallableTool_Tool'
          agent:
            $ref: '#/components/schemas/CallableTool_Agent'
          cadenyaProvidedTool:
            $ref: '#/components/schemas/CallableTool_CadenyaProvidedTool'
      description: >-
        CallableTool is a union that represents a tool that can be called by an
        agent. In Cadenya, a tool that is used within an agent objective
         might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
    Profile:
      required:
        - metadata
        - spec
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/AccountResourceMetadata'
        spec:
          $ref: '#/components/schemas/ProfileSpec'
      description: |-
        A profile identifies a user or non-human principal (such as an API key)
         at the account level. Profiles are account-scoped and can be granted access
         to multiple workspaces.
    ResolvedSecret:
      type: object
      properties:
        key:
          type: string
        source:
          enum:
            - RESOLVED_SECRET_SOURCE_UNSPECIFIED
            - RESOLVED_SECRET_SOURCE_WORKSPACE
            - RESOLVED_SECRET_SOURCE_TOOLSET
            - RESOLVED_SECRET_SOURCE_OBJECTIVE
          type: string
          format: enum
      description: >-
        ResolvedSecret is a resolved secret value from the workspace, toolset,
        or objective. When a tool is called, it will rely
         on secrets in the order of:
         - Objective
         - Toolset
         - Workspace
    BareMetadata:
      type: object
      properties:
        id:
          readOnly: true
          type: string
        name:
          readOnly: true
          type: string
          description: >-
            Human-readable name of the referenced resource, populated by the
            server
             on reads for convenience. Absent on references to resources that do not
             have a name (e.g., objective tasks).
      description: |-
        BareMetadata contains the minimal metadata for a resource: the ID and an
         optional human-readable name. These are used for reference fields where the
         full metadata (account scoping, timestamps, labels, external IDs) is not
         needed — e.g., the tool references inside an agent variation spec or the
         tools assigned to an objective. Both fields are server-populated; clients
         provide IDs through sibling fields rather than by constructing a
         BareMetadata themselves.
    CallableTool_Tool:
      type: object
      required:
        - type
        - tool
      properties:
        type:
          type: string
          enum:
            - tool
        tool:
          $ref: '#/components/schemas/ResourceMetadata'
    CallableTool_Agent:
      type: object
      required:
        - type
        - agent
      properties:
        type:
          type: string
          enum:
            - agent
        agent:
          $ref: '#/components/schemas/ResourceMetadata'
    CallableTool_CadenyaProvidedTool:
      type: object
      required:
        - type
        - cadenyaProvidedTool
      properties:
        type:
          type: string
          enum:
            - cadenyaProvidedTool
        cadenyaProvidedTool:
          $ref: '#/components/schemas/ResourceMetadata'
    AccountResourceMetadata:
      required:
        - id
        - accountId
        - name
        - profileId
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: >-
            Unique identifier for the resource (prefixed ULID, e.g.,
            "apikey_01HXK...")
        accountId:
          readOnly: true
          example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
          type: string
          description: >-
            Account this resource belongs to for multi-tenant isolation
            (prefixed ULID)
        name:
          type: string
          description: >-
            Human-readable name for the resource (e.g., "Customer Support
            Agent", "Email Tool")
             Required for resources that users interact with directly
        externalId:
          type: string
          description: >-
            External ID for the resource (e.g., a workflow ID from an external
            system)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"environment": "production", "team": "platform", "version": "v2"}
        profileId:
          readOnly: true
          example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
          type: string
        createdAt:
          readOnly: true
          type: string
          format: date-time
      description: >-
        AccountResourceMetadata is used to represent a resource that is
        associated to an account but not to a workspace.
    ProfileSpec:
      required:
        - type
      type: object
      properties:
        email:
          type: string
          description: >-
            Email address of the profile. Required and unique within an account
            for
             user profiles.
        name:
          type: string
          description: Display name (e.g., "Bobby Tables").
        type:
          enum:
            - PROFILE_TYPE_UNSPECIFIED
            - PROFILE_TYPE_USER
            - PROFILE_TYPE_API_KEY
            - PROFILE_TYPE_SYSTEM
          type: string
          description: >-
            Whether this profile represents a human user, an API key, or a
            system
             principal.
          format: enum
      description: Configuration for a profile.
    ResourceMetadata:
      required:
        - id
        - accountId
        - workspaceId
        - name
        - profileId
        - createdAt
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: >-
            Unique identifier for the resource (prefixed ULID, e.g.,
            "agent_01HXK...")
        accountId:
          readOnly: true
          example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
          type: string
          description: >-
            Account this resource belongs to for multi-tenant isolation
            (prefixed ULID)
        workspaceId:
          readOnly: true
          example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
          type: string
          description: >-
            Workspace this resource belongs to for organizational grouping
            (prefixed ULID)
        name:
          type: string
          description: >-
            Human-readable name for the resource (e.g., "Customer Support
            Agent", "Email Tool")
             Required for resources that users interact with directly
        externalId:
          type: string
          description: >-
            External ID for the resource (e.g., a workflow ID from an external
            system)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"environment": "production", "team": "platform", "version": "v2"}
        profileId:
          readOnly: true
          example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
          type: string
          description: ID of the actor (user or service account) that created this resource
        createdAt:
          readOnly: true
          type: string
          description: Timestamp when this resource was created
          format: date-time
        updatedAt:
          readOnly: true
          type: string
          description: Timestamp when this resource was last updated
          format: date-time
      description: >-
        Standard metadata for persistent, named resources (e.g., agents, tools,
        prompts)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````