School API

Create Invitation

POST /school/invitations

Before you begin

Requires an authorized account in the school workspace. Class and role checks apply to each request.

POST/school/invitations

Workspace

Example request body

curl --request POST 'https://school.narb.cc/api/school/invitations' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "example",
  "role": "student"
}'

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
`email`	string	Yes	Minimum characters: `3`. Maximum characters: `320`.
`role`	string	Yes	Allowed: `"student"`, `"teacher"`.
`class_ids`	array of string	No	Maximum items: `100`.
`expires_days`	integer	No	Minimum: `1.0`. Maximum: `30.0`. Default: `7`.

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": {
    "email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "title": "Email"
    },
    "role": {
      "$ref": "#/components/schemas/SchoolMembershipRole"
    },
    "class_ids": {
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "type": "array",
      "maxItems": 100,
      "title": "Class Ids"
    },
    "expires_days": {
      "type": "integer",
      "maximum": 30.0,
      "minimum": 1.0,
      "title": "Expires Days",
      "default": 7
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "email",
    "role"
  ],
  "title": "CreateSchoolInvitationRequest"
}

Responses#

200#

Successful Response

{
  "properties": {
    "invitation_id": {
      "type": "string",
      "format": "uuid",
      "title": "Invitation Id"
    },
    "email": {
      "type": "string",
      "title": "Email"
    },
    "role": {
      "$ref": "#/components/schemas/SchoolMembershipRole"
    },
    "class_ids": {
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "type": "array",
      "title": "Class Ids"
    },
    "classes": {
      "items": {
        "$ref": "#/components/schemas/SchoolInvitationClassResponse"
      },
      "type": "array",
      "title": "Classes"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "title": "Expires At"
    },
    "status": {
      "$ref": "#/components/schemas/SchoolInvitationStatus"
    },
    "token": {
      "type": "string",
      "title": "Token"
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "invitation_id",
    "email",
    "role",
    "class_ids",
    "classes",
    "expires_at",
    "status",
    "token"
  ],
  "title": "CreatedSchoolInvitationResponse"
}

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.