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 firstcreatedAt(string (date-time)): When the conversation was startedcredentialId(string): The tenant model credential the conversation runs onid(string (uuid)): Conversation iditemId(string): The item the conversation is aboutlastActivity(string (date-time)): Last message, run or decision in the conversationmodel(string): The model the conversation runs onownerRef(string): E-mail of the person who started it (only they see it)projectId(string): Project of the itemtitle(string): Short title taken from the first messageupdatedAt(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 nowenabled(boolean, required): The project switched the agent onmodels(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 itlabel(string): Display name of the modelmodel(string): Model idprovider(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 startscapTokens(integer): The tenant's monthly token capusedTokens(integer): Tokens used this month
reason(string): WhycanUseis false (one ofdisabled,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"