Hosted agents

Methods, permissions, request fields and response schemas for hosted agents.

Read and search

Retrieve current records, history and status.

List hosted agentsSearch and paginate hosted agents records accessible to your organization.GET/org-agents

Token scope agents:readActor permission managerAction type read

Pagination: Default 50, maximum 100. Follow nextCursor with the same search, tenant and resource until null. Creation cutoff excludes later inserts; mutable fields may change between pages. Unsupported search returns 400.

Query parameters

Field	Type	Description and constraints
`limit`Optional	integer	Minimum 1 · Maximum 100 · Default: 50
`cursor`Optional	string	At least 1 characters · At most 768 characters
`search`Optional	string	At least 0 characters · At most 200 characters

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{data: bounded org-agents summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/org-agents?limit=50" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "email": {
                "type": "string"
              },
              "isManual": {
                "type": "boolean"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "id",
              "name",
              "email",
              "isManual",
              "createdAt"
            ],
            "additionalProperties": false
          },
          "maxItems": 100,
          "minItems": 0
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 768
        }
      },
      "required": [
        "data",
        "nextCursor"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Count unseen agentsNew-agent count.GET/org-agents/new-count

Token scope agents:readActor permission managerAction type read

Explore this request

Edit example fields and validate the request against its schema.

What you receive

New-agent count.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/org-agents/new-count" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "count"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

List assignable accountsSearch and paginate hosted agents records accessible to your organization.GET/org-agents/assignable-accounts

Token scope agents:readActor permission managerAction type read

Query parameters

Field	Type	Description and constraints
`limit`Optional	integer	Minimum 1 · Maximum 100 · Default: 50
`cursor`Optional	string	At least 1 characters · At most 768 characters
`search`Optional	string	At least 0 characters · At most 200 characters

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{data: bounded assignable-accounts summaries[], nextCursor: string | null}. Fetch detail endpoints for full records.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/org-agents/assignable-accounts?limit=50" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "displayName": {
                "type": "string"
              },
              "platform": {
                "type": "string",
                "enum": [
                  "linkedin",
                  "facebook",
                  "x",
                  "upwork",
                  "reddit"
                ]
              },
              "operatingAgentId": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              }
            },
            "required": [
              "id",
              "displayName",
              "platform",
              "operatingAgentId"
            ],
            "additionalProperties": false
          },
          "maxItems": 100,
          "minItems": 0
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 768
        }
      },
      "required": [
        "data",
        "nextCursor"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read a hosted agentAgent details scoped to the token organization.GET/org-agents/:id

Token scope agents:readActor permission managerAction type read

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Agent details scoped to the token organization.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/org-agents/$ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "agent": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 0,
              "maxLength": 5000
            },
            "email": {
              "type": "string",
              "minLength": 0,
              "maxLength": 5000
            },
            "isManual": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "id",
            "name",
            "email",
            "isManual",
            "createdAt"
          ],
          "additionalProperties": true
        },
        "payoutMethods": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "userId": {
                "type": "string",
                "format": "uuid"
              },
              "type": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "isDefault": {
                "type": "boolean"
              },
              "enabled": {
                "type": "boolean"
              },
              "walletAddress": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "walletChain": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "walletCurrency": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "bridgeCustomerId": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "bridgeKycStatus": {
                "type": "string",
                "enum": [
                  "not_started",
                  "pending",
                  "active",
                  "rejected"
                ]
              },
              "bridgePayoutMethodId": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "id",
              "userId",
              "type",
              "label",
              "isDefault",
              "enabled",
              "walletAddress",
              "walletChain",
              "walletCurrency",
              "bridgeCustomerId",
              "bridgeKycStatus",
              "bridgePayoutMethodId",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": true
          }
        },
        "payouts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "amountCents": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "currency": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "status": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "transferId": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "paidAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            },
            "required": [
              "id",
              "amountCents",
              "currency",
              "status",
              "transferId",
              "createdAt",
              "paidAt"
            ],
            "additionalProperties": true
          }
        },
        "accounts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "displayName": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "photoUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "platform": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "status": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "priceInCents": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "agentPayoutRateCents": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "monthlyExpenses": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string",
                      "minLength": 0,
                      "maxLength": 5000
                    },
                    "amountCents": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    }
                  },
                  "required": [
                    "label",
                    "amountCents"
                  ],
                  "additionalProperties": true
                }
              }
            },
            "required": [
              "id",
              "displayName",
              "photoUrl",
              "platform",
              "status",
              "priceInCents",
              "agentPayoutRateCents",
              "monthlyExpenses"
            ],
            "additionalProperties": true
          }
        }
      },
      "required": [
        "agent",
        "payoutMethods",
        "payouts",
        "accounts"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Create and import

Add records, prepare imports or start a new setup.

Add an agent paid off-platformAgent record; without a wallet payroll remains manually payable.POST/org-agents/manual

Token scope agents:writeActor permission managerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Request body

Field	Type	Description and constraints
`email`Required	string · email	At most 200 characters
`name`Optional	string	At least 0 characters · At most 120 characters
`walletAddress`Optional	string	Optional Base USDC receiving wallet. At least 0 characters · At most 42 characters · Pattern: ^0x[a-fA-F0-9]{40}$

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Agent record; without a wallet payroll remains manually payable.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/org-agents/manual" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"email":"operator@example.com"}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 200
    },
    "name": {
      "type": "string",
      "minLength": 0,
      "maxLength": 120
    },
    "walletAddress": {
      "type": "string",
      "minLength": 0,
      "maxLength": 42,
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "Optional Base USDC receiving wallet."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "email": {
          "type": "string",
          "minLength": 0,
          "maxLength": 5000
        }
      },
      "required": [
        "id",
        "name",
        "email"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Update and configure

Change existing records, assignments and configuration.

Assign an account to an agentUpdated account assignment; both resources must belong to the organization.POST/org-agents/:id/assign

Token scope agents:writeActor permission managerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`id`Required	string · uuid	Resource UUID scoped to the current organization.

Request body

Field	Type	Description and constraints
`profileId`Required	string · uuid

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Updated account assignment; both resources must belong to the organization.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/org-agents/$ID/assign" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"profileId":"923ee3b1-2b21-4ce3-8c2c-679e22867541"}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "profileId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "profileId"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Remove an account assignmentUpdated account assignment.POST/org-agents/unassign

Token scope agents:writeActor permission managerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Request body

Field	Type	Description and constraints
`profileId`Required	string · uuid

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Updated account assignment.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/org-agents/unassign" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"profileId":"923ee3b1-2b21-4ce3-8c2c-679e22867541"}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "profileId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "profileId"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Edit agent rate and account costsUpdated economics. A null agentPayoutRateCents clears the override.PATCH/org-agents/accounts/:profileId/economics

Token scope agents:writeActor permission managerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`profileId`Required	string · uuid	Resource UUID scoped to the current organization.

Request body

Field Type Description and constraints

agentPayoutRateCentsOptional integer | null Minimum 0 · Maximum 9007199254740991

monthlyExpensesOptional

array of object

At least 0 items · At most 20 items

Nested fields

Field	Type	Description and constraints
`label`Required	string	At least 0 characters · At most 60 characters
`amountCents`Required	integer	Minimum 0 · Maximum 9007199254740991

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Updated economics. A null agentPayoutRateCents clears the override.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X PATCH "$BASE/org-agents/accounts/$PROFILE_ID/economics" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "agentPayoutRateCents": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "monthlyExpenses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 0,
            "maxLength": 60
          },
          "amountCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "label",
          "amountCents"
        ],
        "additionalProperties": false
      },
      "maxItems": 20,
      "minItems": 0
    }
  },
  "required": [],
  "additionalProperties": false
}

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Lifecycle and actions

Manage transitions, delivery and provider workflows.

Mark agents viewedUpdated viewed marker.POST/org-agents/mark-viewed

Token scope agents:writeActor permission managerAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Updated viewed marker.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/org-agents/mark-viewed" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.