ConnectCloud Developers

Planning agent of an item (tenant:forge:read)

GET /api/forge/v1/projects/{key}/items/{number}/agent

Module: Forge · operationId: getForgeItemAgent · Tag: Agent · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:read and edit rights on the item. Answers whether the caller can use the planning agent (ADR 0028) on the item now (status) and the caller's own conversations about it, latest activity first. A hidden item answers 404, a visible one the caller may not edit 403.

Parameters

Name In Type Required Description
key path string yes Project key (e.g. APP)
number path integer yes Item number in the project (12 of APP-12)

Responses

  • 200 Agent panel (application/json)
  • 401 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 503 Error (application/json)

Fields of the 200 answer:

  • conversations (array of AgentConversation, required): The caller's own conversations about the item, latest activity first
    • createdAt (string (date-time)): When the conversation was started
    • credentialId (string): The tenant model credential the conversation runs on
    • id (string (uuid)): Conversation id
    • itemId (string): The item the conversation is about
    • lastActivity (string (date-time)): Last message, run or decision in the conversation
    • model (string): The model the conversation runs on
    • ownerRef (string): E-mail of the person who started it (only they see it)
    • projectId (string): Project of the item
    • title (string): Short title taken from the first message
    • updatedAt (string (date-time)): Last change of the conversation row
  • status (AgentStatus, required)
    • canUse (boolean, required): The caller can start the planning agent on the item now
    • enabled (boolean, required): The project switched the agent on
    • models (array of AgentModel, required): The tenant's usable models (bring your own key)
      • credentialId (string): Id of the tenant credential (bring your own key)
      • credentialName (string): Name of the credential as the tenant set it
      • label (string): Display name of the model
      • model (string): Model id
      • provider (string): Provider of the credential
    • budget (object): The tenant's agent token budget of the month (missing when it could not be read)
      • capReached (boolean): The cap is reached; no new run starts
      • capTokens (integer): The tenant's monthly token cap
      • usedTokens (integer): Tokens used this month
    • reason (string): Why canUse is false (one of disabled, no_credentials, cap_reached, unavailable)

Example 200 answer:

{
  "conversations": [
    {
      "createdAt": "2026-11-17T14:02:00Z",
      "credentialId": "6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b01",
      "id": "7d8e9f0a-1b2c-4d3e-8f4a-6b7c8d9e0f01",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06",
      "lastActivity": "2026-11-17T14:06:00Z",
      "model": "claude-sonnet-4-5",
      "ownerRef": "marie.wagner@muster-it.example",
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "title": "Akzeptanzkriterien für die Filterleiste",
      "updatedAt": "2026-11-17T14:06:00Z"
    }
  ],
  "status": {
    "budget": {
      "capReached": false,
      "capTokens": 5000000,
      "usedTokens": 1284000
    },
    "canUse": true,
    "enabled": true,
    "models": [
      {
        "credentialId": "6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b01",
        "credentialName": "Anthropic Muster IT",
        "label": "Claude Sonnet 4.5",
        "model": "claude-sonnet-4-5",
        "provider": "anthropic"
      }
    ]
  }
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/agent' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI