Menu
GETPOST agents/ Service tier

List agents, or create one with POST. derived from route

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/

Query parameters

NameDefault
statusnone
workspacenone

Body keys (JSON)

KeyRequiredDefault
connector_node_typesoptional or conditionalnone
connector_slugsoptional or conditionalnone
inbox_modeoptional or conditionalnone
max_turnsoptional or conditionalnone
modeloptional or conditionalnone
nameoptional or conditionalnone
statusoptional or conditionalnone
system_promptoptional or conditionalnone
tool_namesoptional or conditionalnone
voice_idoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Pagination

Accepts limit and offset. The response meta carries total, limit and offset.

Responses

200 data and meta envelope

{
  "data": [
    {
      "id": "...",
      "name": "...",
      "description": "...",
      "icon": "...",
      "avatar_url": "...",
      "status": "...",
      "model": "...",
      "workspace_public_id": "...",
      "created_by_email": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "system_prompt": "...",
      "personality": "...",
      "voice_provider": "...",
      "voice_id": "...",
      "voice_secret_id": "...",
      "voice_instructions": "...",
      "voice_filler": "...",
      "voice_model": "...",
      "message_model": "...",
      "voice_turn_mode": "...",
      "call_transcript": "...",
      "call_review": "...",
      "created_by_agent": "...",
      "max_turns": 0,
      "tool_scope": "...",
      "connector_scope": "...",
      "tool_names": [
        "..."
      ],
      "connector_slugs": [
        "..."
      ],
      "connector_node_types": [
        "..."
      ],
      "can_manage": "...",
      "grants": [
        {
          "id": "...",
          "grant_type": "...",
          "user_email": "...",
          "role": "...",
          "granted_by_email": "...",
          "granted_at": "2026-01-01T00:00:00Z"
        }
      ],
      "knowledge_sources": [
        {
          "id": "...",
          "app": "...",
          "kind": "...",
          "ref_id": "...",
          "label": "...",
          "mode": "...",
          "position": 0,
          "has_content": true
        }
      ],
      "skills": [
        {
          "id": "...",
          "name": "...",
          "description": "...",
          "instructions": "...",
          "tool_names": [
            "..."
          ],
          "enabled": true,
          "position": 0
        }
      ],
      "schedules": [
        {
          "id": "...",
          "name": "...",
          "cron_expression": "...",
          "run_at": "2026-01-01T00:00:00Z",
          "timezone": "...",
          "prompt": "...",
          "space_id": "...",
          "status": "...",
          "next_fire_at": "2026-01-01T00:00:00Z",
          "last_fire_at": "2026-01-01T00:00:00Z",
          "total_invocations": 0,
          "max_invocations": "...",
          "consecutive_errors": "...",
          "conversation_id": "...",
          "created_by_email": "...",
          "model": "...",
          "preset": "...",
          "variables": {
            "...": "..."
          }
        }
      ],
      "memory": "..."
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

201 data and meta envelope

{
  "data": {
    "id": "...",
    "name": "...",
    "description": "...",
    "icon": "...",
    "avatar_url": "...",
    "status": "...",
    "model": "...",
    "workspace_public_id": "...",
    "created_by_email": "...",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "system_prompt": "...",
    "personality": "...",
    "voice_provider": "...",
    "voice_id": "...",
    "voice_secret_id": "...",
    "voice_instructions": "...",
    "voice_filler": "...",
    "voice_model": "...",
    "message_model": "...",
    "voice_turn_mode": "...",
    "call_transcript": "...",
    "call_review": "...",
    "created_by_agent": "...",
    "max_turns": 0,
    "tool_scope": "...",
    "connector_scope": "...",
    "tool_names": [
      "..."
    ],
    "connector_slugs": [
      "..."
    ],
    "connector_node_types": [
      "..."
    ],
    "can_manage": "...",
    "grants": [
      {
        "id": "...",
        "grant_type": "...",
        "user_email": "...",
        "role": "...",
        "granted_by_email": "...",
        "granted_at": "2026-01-01T00:00:00Z"
      }
    ],
    "knowledge_sources": [
      {
        "id": "...",
        "app": "...",
        "kind": "...",
        "ref_id": "...",
        "label": "...",
        "mode": "...",
        "position": 0,
        "has_content": true
      }
    ],
    "skills": [
      {
        "id": "...",
        "name": "...",
        "description": "...",
        "instructions": "...",
        "tool_names": [
          "..."
        ],
        "enabled": true,
        "position": 0
      }
    ],
    "schedules": [
      {
        "id": "...",
        "name": "...",
        "cron_expression": "...",
        "run_at": "2026-01-01T00:00:00Z",
        "timezone": "...",
        "prompt": "...",
        "space_id": "...",
        "status": "...",
        "next_fire_at": "2026-01-01T00:00:00Z",
        "last_fire_at": "2026-01-01T00:00:00Z",
        "total_invocations": 0,
        "max_invocations": "...",
        "consecutive_errors": "...",
        "conversation_id": "...",
        "created_by_email": "...",
        "model": "...",
        "preset": "...",
        "variables": {
          "...": "..."
        }
      }
    ],
    "memory": "..."
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "connector_node_types": "...",
  "connector_slugs": "...",
  "inbox_mode": "...",
  "max_turns": "...",
  "model": "...",
  "name": "...",
  "status": "...",
  "system_prompt": "..."
}'

Source: MatterCore/agents_api.py (agents_api.agents)

GET agents/project-access/ Service tier

The role an agent identity holds on a Productivity project through its knowledge sources (``data.role``).

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/project-access/

Query parameters

NameDefault
emailnone
project_idnone

Responses

200 data and meta envelope

{
  "data": {
    "role": "...",
    "agent": "..."
  }
}

200 data and meta envelope

{
  "data": {
    "role": "none",
    "agent": null
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/agents/project-access/?email=...&project_id=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/knowledge_api.py (knowledge_api.agent_project_access)

GETPOSTDELETE agents/{public_id}/ Service tier

Read, change or delete one of the agents by id. derived from route

This read is not paginated. It returns at most 300 rows and does not report a total, so a result of exactly 300 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
connector_node_typesoptional or conditionalnone
connector_slugsoptional or conditionalnone
inbox_modeoptional or conditionalnone
max_turnsoptional or conditionalnone
modeloptional or conditionalnone
nameoptional or conditionalnone
statusoptional or conditionalnone
system_promptoptional or conditionalnone
tool_namesoptional or conditionalnone
voice_idoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "id": "...",
    "name": "...",
    "description": "...",
    "icon": "...",
    "avatar_url": "...",
    "status": "...",
    "model": "...",
    "workspace_public_id": "...",
    "created_by_email": "...",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "system_prompt": "...",
    "personality": "...",
    "voice_provider": "...",
    "voice_id": "...",
    "voice_secret_id": "...",
    "voice_instructions": "...",
    "voice_filler": "...",
    "voice_model": "...",
    "message_model": "...",
    "voice_turn_mode": "...",
    "call_transcript": "...",
    "call_review": "...",
    "created_by_agent": "...",
    "max_turns": 0,
    "tool_scope": "...",
    "connector_scope": "...",
    "tool_names": [
      "..."
    ],
    "connector_slugs": [
      "..."
    ],
    "connector_node_types": [
      "..."
    ],
    "can_manage": "...",
    "grants": [
      {
        "id": "...",
        "grant_type": "...",
        "user_email": "...",
        "role": "...",
        "granted_by_email": "...",
        "granted_at": "2026-01-01T00:00:00Z"
      }
    ],
    "knowledge_sources": [
      {
        "id": "...",
        "app": "...",
        "kind": "...",
        "ref_id": "...",
        "label": "...",
        "mode": "...",
        "position": 0,
        "has_content": true
      }
    ],
    "skills": [
      {
        "id": "...",
        "name": "...",
        "description": "...",
        "instructions": "...",
        "tool_names": [
          "..."
        ],
        "enabled": true,
        "position": 0
      }
    ],
    "schedules": [
      {
        "id": "...",
        "name": "...",
        "cron_expression": "...",
        "run_at": "2026-01-01T00:00:00Z",
        "timezone": "...",
        "prompt": "...",
        "space_id": "...",
        "status": "...",
        "next_fire_at": "2026-01-01T00:00:00Z",
        "last_fire_at": "2026-01-01T00:00:00Z",
        "total_invocations": 0,
        "max_invocations": "...",
        "consecutive_errors": "...",
        "conversation_id": "...",
        "created_by_email": "...",
        "model": "...",
        "preset": "...",
        "variables": {
          "...": "..."
        }
      }
    ],
    "memory": "..."
  }
}

200 data and meta envelope

{
  "data": {
    "deleted": true,
    "id": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
403manage_required
404agent_not_found

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "connector_node_types": "...",
  "connector_slugs": "...",
  "inbox_mode": "...",
  "max_turns": "...",
  "model": "...",
  "name": "...",
  "status": "...",
  "system_prompt": "..."
}'

Source: MatterCore/agents_api.py (agents_api.agent_detail)

GETPOST agents/{public_id}/grants/ Service tier

Read or change one of the agents by id. derived from route

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/grants/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
grant_typeoptional or conditionalnone
roleoptional or conditionalnone
user_emailoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": [
    {
      "id": "...",
      "grant_type": "...",
      "user_email": "...",
      "role": "...",
      "granted_by_email": "...",
      "granted_at": "2026-01-01T00:00:00Z"
    }
  ]
}

200 data and meta envelope

{
  "data": {
    "removed": true
  }
}

201 data and meta envelope

{
  "data": {
    "id": "...",
    "grant_type": "...",
    "user_email": "...",
    "role": "...",
    "granted_by_email": "...",
    "granted_at": "2026-01-01T00:00:00Z"
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_grant_type
400invalid_role
400last_manage_grant
400unknown_action
400user_email_required
403manage_required
404agent_not_found
404grant_not_found
409grant_exists

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/grants/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "grant_type": "...",
  "role": "...",
  "user_email": "..."
}'

Source: MatterCore/agents_api.py (agents_api.agent_grants)

GETPOST agents/{public_id}/knowledge/ Service tier

Read or change one of the agents by id. derived from route

This read is not paginated. It returns at most 200 rows and does not report a total, so a result of exactly 200 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/agents/{public_id}/knowledge/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
appoptional or conditionalnone
contentoptional or conditionalnone
idoptional or conditionalnone
kindoptional or conditionalnone
labeloptional or conditionalnone
modeoptional or conditionalnone
positionoptional or conditionalnone
ref_idoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": [
    {
      "id": "...",
      "app": "...",
      "kind": "...",
      "ref_id": "...",
      "label": "...",
      "mode": "...",
      "position": 0,
      "has_content": true
    }
  ]
}

200 data and meta envelope

{
  "data": {
    "id": "...",
    "app": "...",
    "kind": "...",
    "ref_id": "...",
    "label": "...",
    "mode": "...",
    "position": 0,
    "has_content": true
  }
}

200 data and meta envelope

{
  "data": {
    "removed": true
  }
}

201 data and meta envelope

{
  "data": {
    "id": "...",
    "app": "...",
    "kind": "...",
    "ref_id": "...",
    "label": "...",
    "mode": "...",
    "position": 0,
    "has_content": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400content_not_allowed
400invalid_kind
400invalid_mode
400invalid_position
400ref_required
400unknown_action
403manage_required
404agent_not_found
404source_not_found

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/agents/PUBLIC_ID/knowledge/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "app": "...",
  "content": "...",
  "id": "...",
  "kind": "...",
  "label": "...",
  "mode": "...",
  "position": "..."
}'

Source: MatterCore/agents_api.py (agents_api.agent_knowledge)

GET knowledge-kinds/ Service tier

The (app, kind) catalog: consumers discover container kinds the way Forms consumers discover mapping targets.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/knowledge-kinds/

Responses

200 data and meta envelope

{
  "data": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/knowledge-kinds/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/agents_api.py (agents_api.knowledge_kinds)

All Agents resources
Start Free Explore our Products