API reference

Dispositions

Define the questions answered from each call's transcript, and group them into categories.

A disposition is a question the platform answers after a call by reading the transcript, for example "Is the customer interested?". The answers land in the execution's extracted_data. Dispositions are grouped into extraction categories. A category belongs to one agent; a disposition can be linked to several agents. See Post-call data.

All routes need Authorization: Bearer <key>. Reading needs the viewer role; everything else needs member.

Operation	Method and path
Create a disposition	`POST /dispositions/`
Create several dispositions	`POST /dispositions/bulk`
List dispositions	`GET /dispositions/`
Get a disposition	`GET /dispositions/{disposition_id}`
Update a disposition	`PUT /dispositions/{disposition_id}`
Delete a disposition	`DELETE /dispositions/{disposition_id}`
Test dispositions on a transcript	`POST /v2/agent/{agent_id}/dispositions/test`
Create a category	`POST /agent/{agent_id}/extraction-categories`
List an agent's categories	`GET /agent/{agent_id}/extraction-categories`
Update a category	`PATCH /extraction-categories/{category_id}`
Delete a category	`DELETE /extraction-categories/{category_id}`

The collection routes also answer without the trailing slash (/dispositions).

Disposition fields

Field	Type	Required	Description
`name`	string	yes	Short label; the key of the answer in `extracted_data`.
`question`	string	yes	What to find out from the transcript.
`is_subjective`	boolean	one must be `true`	Produce a free-form answer. Default `false`.
`is_objective`	boolean	one must be `true`	Pick one of `objective_options`. Default `false`.
`objective_options`	array	when `is_objective`	Objects with a `value` and a `condition` that says when the value applies.
`subjective_type`	string	no	`text`, `timestamp`, `numeric`, `boolean`, `email` or `regex`. Default `text`.
`subjective_type_config`	object	when type is `regex`	`{"pattern": "..."}`.
`model`	string	no	The model used for extraction. Default `gpt-4.1-mini`. See below.
`category`	string	no	Category name. A new name creates the category on the agent. Default `General`.
`category_id`	string	no	An existing category of the agent. Send `category` or `category_id`, not both.

Accepted model values: gpt-4.1-mini, gpt-4.1-nano, gpt-4o-mini, gpt-5-mini, gpt-5-nano, gpt-5.4-mini, gpt-5.6-luna, gemini-3.5-flash, gemini-3.5-flash-lite.

Limitation: A language model performs the extraction only when the account has an OpenAI-compatible provider key (or the agent runs on the platform's local model). Without one, answers come from simple keyword rules over the transcript, and the model field has no effect.

Operations

Create a disposition

POST /dispositions/

Creates a disposition and links it to an agent.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`agent_id`	body	string (UUID)	yes	The agent to link the disposition to.
other fields	body			See Disposition fields.

Request

bash

curl -X POST https://api.sevennadi.si/dispositions/ \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "f412f2b1-3493-4458-bcf2-8676cc798edd",
    "name": "Interested",
    "question": "Is the customer interested in the offer?",
    "is_objective": true,
    "objective_options": [
      {"value": "yes", "condition": "The customer agrees"},
      {"value": "no", "condition": "The customer declines"}
    ]
  }'

Response 201 Created

json

{
  "message": "Disposition created successfully",
  "id": "ffb28a5d-633c-42d2-9112-e9905bf33f24",
  "category_id": "af8de679-016f-4be6-aa6b-5636f2116b78"
}

Errors

Status	Message
400	`agent_id is required`
400	`name is required`, `question is required`
400	`At least one of is_subjective or is_objective must be true`
400	`objective_options is required and must be non-empty when is_objective is true`
400	`Each objective option needs a value and a condition`
400	`subjective_type must be one of: text, timestamp, numeric, boolean, email, regex`
400	`subjective_type_config.pattern is required when subjective_type is regex`
400	`Provide either category_id or category, not both`
404	`Agent not found`
404	`Category not found for this agent`
422	`model must be one of: gpt-4.1-mini, gpt-4.1-nano, ...`

Create several dispositions

POST /dispositions/bulk

Creates several dispositions for one agent in a single request. It is all or nothing: if one item is invalid, none is created.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`agent_id`	body	string (UUID)	yes	The agent.
`dispositions`	body	array	yes	One or more objects with the disposition fields.

Request

bash

curl -X POST https://api.sevennadi.si/dispositions/bulk \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "f412f2b1-3493-4458-bcf2-8676cc798edd",
    "dispositions": [
      {"name": "Callback time", "question": "When should we call back?", "is_subjective": true, "subjective_type": "timestamp", "category": "Follow-up"},
      {"name": "Reason", "question": "Why did the customer decline?", "is_subjective": true, "category": "Follow-up"}
    ]
  }'

Response 201 Created

json

{
  "message": "Dispositions created successfully",
  "ids": ["1b2a3c4d-5e6f-4071-8293-a4b5c6d7e8f9", "2c3b4d5e-6f70-4182-93a4-b5c6d7e8f9a0"]
}

Errors

Status	Message
400	`agent_id is required`
400	`dispositions must be a non-empty array`
400 or 422	`dispositions[<index>]: <message>`, with the message of Create a disposition for the first invalid item
404	`Agent not found`

List dispositions

GET /dispositions/

Returns the account's dispositions, oldest first, or only those linked to one agent.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`agent_id`	query	string (UUID)	no	Only dispositions linked to this agent.

Request

bash

curl "https://api.sevennadi.si/dispositions/?agent_id=f412f2b1-3493-4458-bcf2-8676cc798edd" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

[
  {
    "id": "ffb28a5d-633c-42d2-9112-e9905bf33f24",
    "name": "Interested",
    "question": "Is the customer interested in the offer?",
    "category": "General",
    "category_id": "af8de679-016f-4be6-aa6b-5636f2116b78",
    "model": "gpt-4.1-mini",
    "is_subjective": false,
    "is_objective": true,
    "subjective_type": "text",
    "subjective_type_config": null,
    "objective_options": [
      {"value": "yes", "condition": "The customer agrees"},
      {"value": "no", "condition": "The customer declines"}
    ],
    "agent_ids": ["f412f2b1-3493-4458-bcf2-8676cc798edd"],
    "created_by": "4a257495-4e4b-484e-92e5-c616a720ec03",
    "created_at": "2026-10-13T07:22:03Z",
    "updated_at": "2026-10-13T07:22:03Z"
  }
]

Errors

Status	Message
404	`Agent not found`

Get a disposition

GET /dispositions/{disposition_id}

Returns one disposition.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`disposition_id`	path	string (UUID)	yes	The disposition.
`agent_id`	query	string (UUID)	no	Also check that the disposition is linked to this agent.

Request

bash

curl https://api.sevennadi.si/dispositions/ffb28a5d-633c-42d2-9112-e9905bf33f24 \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

A disposition object, as in List dispositions.

Errors

Status	Message
404	`Disposition not found`
404	`Disposition not found for this agent`

Update a disposition

PUT /dispositions/{disposition_id}

Changes the fields you send; the rest keep their values. The merged result must pass the checks of create.

A disposition may be shared by several agents. If you send agent_id and other agents share the disposition, the change is applied to a copy that is linked to that agent only, and the response is 201 with the copy's id. Without agent_id, the disposition changes for every agent that uses it.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`disposition_id`	path	string (UUID)	yes	The disposition.
`agent_id`	body	string (UUID)	no	Apply the change for this agent only.
`category` or `category_id`	body	string	no	Move the disposition to another category of the agent. A category left empty by the move is removed.
other fields	body		no	Any of `name`, `question`, `model`, `is_subjective`, `is_objective`, `subjective_type`, `subjective_type_config`, `objective_options`.

Request

bash

curl -X PUT https://api.sevennadi.si/dispositions/ffb28a5d-633c-42d2-9112-e9905bf33f24 \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"question": "Did the customer agree to renew?", "category": "Renewal"}'

Response 200 OK

json

{
  "message": "Disposition updated successfully",
  "id": "ffb28a5d-633c-42d2-9112-e9905bf33f24",
  "category_id": "c4d5e6f7-0812-4a3b-9c4d-5e6f70819203"
}

When a copy was made, the status is 201 Created and the message is Disposition copy created and linked to agent.

Errors

Status	Message
400	`No valid fields provided to update`
400	The validation messages of Create a disposition
404	`Disposition not found`
404	`Disposition not found for this agent`
404	`Category not found for this agent`

Delete a disposition

DELETE /dispositions/{disposition_id}

Deletes a disposition and its links to agents. If its category becomes empty, the category is removed too.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`disposition_id`	path	string (UUID)	yes	The disposition.

Request

bash

curl -X DELETE https://api.sevennadi.si/dispositions/ffb28a5d-633c-42d2-9112-e9905bf33f24 \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{"message": "Disposition deleted successfully", "id": "ffb28a5d-633c-42d2-9112-e9905bf33f24"}

Errors

Status	Message
404	`Disposition not found`

Test dispositions on a transcript

POST /v2/agent/{agent_id}/dispositions/test

Runs the agent's dispositions against a transcript you supply and returns the extracted data, without a call. Use it to tune questions and options.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`agent_id`	path	string (UUID)	yes	The agent whose dispositions run.
`transcript`	body	string	yes	At most 50,000 characters. Use the transcript format of executions: one `role: text` line per turn.

Request

bash

curl -X POST https://api.sevennadi.si/v2/agent/f412f2b1-3493-4458-bcf2-8676cc798edd/dispositions/test \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"transcript": "assistant: Would you like to renew your policy?\nuser: Yes, sure, please go ahead."}'

Response 200 OK

json

{
  "extracted_data": {
    "General": {
      "Interested": {"objective": "yes"}
    }
  }
}

The result is keyed by category, then by disposition name. Each answer has subjective, objective or both, depending on the disposition. An agent without dispositions returns an empty object.

Errors

Status	Message
400	`transcript is required`
400	`transcript must be at most 50000 characters`
404	`Agent not found`

Create a category

POST /agent/{agent_id}/extraction-categories

Creates an empty extraction category on an agent. You rarely need this: naming a new category when you create a disposition creates the category for you.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`agent_id`	path	string (UUID)	yes	The agent.
`name`	body	string	yes	Category name, unique on the agent.
`model`	body	string	yes	One of the accepted models.

Request

bash

curl -X POST https://api.sevennadi.si/agent/f412f2b1-3493-4458-bcf2-8676cc798edd/extraction-categories \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing", "model": "gpt-4.1-mini"}'

Response 201 Created

json

{
  "id": "7b70f638-6c14-45f2-8306-bb747398b0cc",
  "name": "Billing",
  "model": "gpt-4.1-mini",
  "agent_id": "f412f2b1-3493-4458-bcf2-8676cc798edd",
  "created_at": "2026-10-13T07:22:04Z",
  "updated_at": "2026-10-13T07:22:04Z"
}

Errors

Status	Message
400	`A category with this name is already attached to the agent`
404	`Agent not found`
422	`name is required`
422	`model must be one of: gpt-4.1-mini, gpt-4.1-nano, ...`

List an agent's categories

GET /agent/{agent_id}/extraction-categories

Returns the agent's categories, oldest first, each with its dispositions.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`agent_id`	path	string (UUID)	yes	The agent.

Request

bash

curl https://api.sevennadi.si/agent/f412f2b1-3493-4458-bcf2-8676cc798edd/extraction-categories \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{
  "categories": [
    {
      "id": "af8de679-016f-4be6-aa6b-5636f2116b78",
      "name": "General",
      "model": "gpt-4.1-mini",
      "dispositions": [
        {"id": "ffb28a5d-633c-42d2-9112-e9905bf33f24", "name": "Interested", "category": "General"}
      ]
    }
  ]
}

Each entry of dispositions is a full disposition object.

Errors

Status	Message
404	`Agent not found`

Update a category

PATCH /extraction-categories/{category_id}

Renames a category, changes its model, or both.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`category_id`	path	string (UUID)	yes	The category.
`name`	body	string	one of the two	New name, unique on the agent.
`model`	body	string	one of the two	One of the accepted models.

Request

bash

curl -X PATCH https://api.sevennadi.si/extraction-categories/7b70f638-6c14-45f2-8306-bb747398b0cc \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"name": "Payments"}'

Response 200 OK

The category object, as in Create a category.

Errors

Status	Message
400	`A category with this name is already attached to the agent`
404	`Category not found`
422	`Provide name, model, or both`
422	`name must not be empty`
422	`model must be one of: gpt-4.1-mini, gpt-4.1-nano, ...`

Delete a category

DELETE /extraction-categories/{category_id}

Deletes a category together with every disposition in it.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`category_id`	path	string (UUID)	yes	The category.

Request

bash

curl -X DELETE https://api.sevennadi.si/extraction-categories/7b70f638-6c14-45f2-8306-bb747398b0cc \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{"message": "Category deleted successfully", "id": "7b70f638-6c14-45f2-8306-bb747398b0cc"}

Errors

Status	Message
404	`Category not found`