API reference

Create Agent

Before you begin

This page uses Nexus's generated request and response schema. Requests still require the correct account, workspace, and resource permissions.

POST/persona

Workspace

Example request body

curl --request POST 'https://school.narb.cc/api/persona' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "example",
  "description": "example",
  "document_set_ids": [],
  "tool_ids": [],
  "system_prompt": "example",
  "task_prompt": "example",
  "datetime_aware": false
}'

This builds a request example. Fill in required query values, then replace path placeholders and YOUR_TOKEN in your own environment. Use a token for a user with access to this workspace. Responses and permissions depend on your account and deployment. Never paste a private token into documentation.

Download the Nexus OpenAPI schema ↗
Import the schema into your API client. It describes the backend source; enabled routes depend on your workspace.

Authentication and scope#

Send requests to the workspace that owns the resource. Authentication does not by itself grant a school membership, class assignment, or administrator permission. School endpoints apply their role and class checks on the server.

Use a credential issued for that workspace with only the permissions your integration needs. Keep it on your server. Do not place credentials in a public website or a shared skill.

Parameters#

Name	Location	Required	Type
`tenant_id`	query	No	string or null

The tenant_id parameter is part of the engine schema. It does not authorize a caller to another school. Use the workspace and permissions assigned to your account.

Request body#

Content type: application/json.

Field	Type	Required	Details
`name`	string	Yes	See Request schema.
`description`	string	Yes	See Request schema.
`document_set_ids`	array of integer	Yes	See Request schema.
`is_public`	boolean or null	No	See Request schema.
`default_model_configuration_id`	integer or null	No	See Request schema.
`starter_messages`	array of object or null	No	See Request schema.
`users`	array of string or null	No	See Request schema.
`groups`	array of integer or null	No	See Request schema.
`tool_ids`	array of integer	Yes	See Request schema.
`remove_image`	boolean or null	No	See Request schema.
`uploaded_image_id`	string or null	No	See Request schema.
`icon_name`	string or null	No	See Request schema.
`search_start_date`	string or null	No	See Request schema.
`label_ids`	array of integer or null	No	See Request schema.
`is_featured`	boolean or null	No	See Request schema.
`display_priority`	integer or null	No	See Request schema.
`user_file_ids`	array of string or null	No	See Request schema.
`hierarchy_node_ids`	array of integer or null	No	See Request schema.
`document_ids`	array of string or null	No	See Request schema.
`system_prompt`	string	Yes	See Request schema.
`replace_base_system_prompt`	boolean	No	Default: `false`.
`task_prompt`	string	Yes	See Request schema.
`datetime_aware`	boolean	Yes	See Request schema.

Request schema#

The schema includes field limits and required values. Referenced types are included in the downloadable OpenAPI file. Replace example identifiers with IDs from your workspace.

{
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "description": {
      "type": "string",
      "title": "Description"
    },
    "document_set_ids": {
      "items": {
        "type": "integer"
      },
      "type": "array",
      "title": "Document Set Ids"
    },
    "is_public": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Is Public"
    },
    "default_model_configuration_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Default Model Configuration Id"
    },
    "starter_messages": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StarterMessage"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Starter Messages"
    },
    "users": {
      "anyOf": [
        {
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Users"
    },
    "groups": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Groups"
    },
    "tool_ids": {
      "items": {
        "type": "integer"
      },
      "type": "array",
      "title": "Tool Ids"
    },
    "remove_image": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Remove Image"
    },
    "uploaded_image_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Uploaded Image Id"
    },
    "icon_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Icon Name"
    },
    "search_start_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Search Start Date"
    },
    "label_ids": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Label Ids"
    },
    "is_featured": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Is Featured"
    },
    "display_priority": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Display Priority"
    },
    "user_file_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "User File Ids"
    },
    "hierarchy_node_ids": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hierarchy Node Ids"
    },
    "document_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Ids"
    },
    "system_prompt": {
      "type": "string",
      "title": "System Prompt"
    },
    "replace_base_system_prompt": {
      "type": "boolean",
      "title": "Replace Base System Prompt",
      "default": false
    },
    "task_prompt": {
      "type": "string",
      "title": "Task Prompt"
    },
    "datetime_aware": {
      "type": "boolean",
      "title": "Datetime Aware"
    }
  },
  "type": "object",
  "required": [
    "name",
    "description",
    "document_set_ids",
    "tool_ids",
    "system_prompt",
    "task_prompt",
    "datetime_aware"
  ],
  "title": "PersonaUpsertRequest"
}

Responses#

200#

Successful Response

{
  "properties": {
    "id": {
      "type": "integer",
      "title": "Id"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "description": {
      "type": "string",
      "title": "Description"
    },
    "is_public": {
      "type": "boolean",
      "title": "Is Public"
    },
    "is_listed": {
      "type": "boolean",
      "title": "Is Listed"
    },
    "uploaded_image_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Uploaded Image Id"
    },
    "icon_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Icon Name"
    },
    "user_file_ids": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "User File Ids"
    },
    "display_priority": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Display Priority"
    },
    "is_featured": {
      "type": "boolean",
      "title": "Is Featured"
    },
    "builtin_persona": {
      "type": "boolean",
      "title": "Builtin Persona"
    },
    "starter_messages": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StarterMessage"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Starter Messages"
    },
    "tools": {
      "items": {
        "$ref": "#/components/schemas/ToolSnapshot"
      },
      "type": "array",
      "title": "Tools"
    },
    "labels": {
      "items": {
        "$ref": "#/components/schemas/PersonaLabelSnapshot"
      },
      "type": "array",
      "title": "Labels"
    },
    "owner": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/MinimalUserSnapshot"
        },
        {
          "type": "null"
        }
      ]
    },
    "owner_group": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/PersonaOwnerGroupSnapshot"
        },
        {
          "type": "null"
        }
      ]
    },
    "users": {
      "items": {
        "$ref": "#/components/schemas/MinimalUserSnapshot"
      },
      "type": "array",
      "title": "Users"
    },
    "groups": {
      "items": {
        "type": "integer"
      },
      "type": "array",
      "title": "Groups"
    },
    "user_shares": {
      "items": {
        "$ref": "#/components/schemas/PersonaUserShare"
      },
      "type": "array",
      "title": "User Shares"
    },
    "group_shares": {
      "items": {
        "$ref": "#/components/schemas/PersonaGroupShare"
      },
      "type": "array",
      "title": "Group Shares"
    },
    "public_permission": {
      "$ref": "#/components/schemas/PersonaSharePermission"
    },
    "sharing_status": {
      "$ref": "#/components/schemas/PersonaSharingStatus"
    },
    "document_sets": {
      "items": {
        "$ref": "#/components/schemas/DocumentSetSummary"
      },
      "type": "array",
      "title": "Document Sets"
    },
    "default_model_configuration_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Default Model Configuration Id"
    },
    "hierarchy_nodes": {
      "items": {
        "$ref": "#/components/schemas/HierarchyNodeSnapshot"
      },
      "type": "array",
      "title": "Hierarchy Nodes"
    },
    "attached_documents": {
      "items": {
        "$ref": "#/components/schemas/AttachedDocumentSnapshot"
      },
      "type": "array",
      "title": "Attached Documents"
    },
    "permissions": {
      "additionalProperties": {
        "type": "boolean"
      },
      "type": "object",
      "title": "Permissions"
    },
    "system_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "System Prompt"
    },
    "replace_base_system_prompt": {
      "type": "boolean",
      "title": "Replace Base System Prompt",
      "default": false
    },
    "task_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Task Prompt"
    },
    "datetime_aware": {
      "type": "boolean",
      "title": "Datetime Aware",
      "default": true
    }
  },
  "type": "object",
  "required": [
    "id",
    "name",
    "description",
    "is_public",
    "is_listed",
    "uploaded_image_id",
    "icon_name",
    "user_file_ids",
    "display_priority",
    "is_featured",
    "builtin_persona",
    "starter_messages",
    "tools",
    "labels",
    "owner",
    "owner_group",
    "users",
    "groups",
    "user_shares",
    "group_shares",
    "public_permission",
    "sharing_status",
    "document_sets"
  ],
  "title": "PersonaSnapshot"
}

422#

Validation Error

{
  "properties": {
    "detail": {
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Access and error handling#

A signed-out or expired session needs authentication. A denied request can mean the account lacks permission, class membership, an approved model, or an available allowance. Do not retry a write blindly after a network failure; first check whether it was recorded.

Treat validation errors as a request problem. Use the returned field details to correct the request. Resource identifiers do not confer access.

Schema version#

Generated from Nexus backend source fe1c3a07c793029d3d87191a68f89e481afd6bc8. Check your deployed version before integrating. Schema coverage is not a live acceptance test.