Assignments

Assigned work.

GET/v1/assignments

Set work

createAssignmentassignments:writewrite: 120/min per keyIdempotency-KeySince 2026-10-01

For a class or team (unitId: everyone in it and below) or for named learners (personIds), in one subject. An API key sets work for any class, team or learner in the organization, as an owner or admin does in the console. Named learners must hold a learner's place in the organization (400 invalid_request otherwise). The focus, difficulty and target must be ones the subject offers (400 invalid_request otherwise). Refused on a unit that is switched off, or where homework is switched off (409 conflict, details.reason). Each learner's state then moves on its own: started when they begin a session in the subject, completed when what they did meets the assignment (an assessment's on a confirmed pass).

Body

subjectIdstringrequired
The subject the work is in.
titlestringrequired
1-120 characters
instructionsstring | null
unitIdstring | null
Set it for a class or team: every learner in it and below.
personIdsstring[] | null
Or for named learners (up to 500), each holding a learner's place here.
skillsstring[] | null
The subject's skill ids it covers.
minutesinteger | null
Minutes of counting sessions it asks for.
dueAtstring | null
focusobject | null
One of the subject's topics, question sets or scenarios, by id.
- idstringrequired
  1-80 characters
difficulty"easy" | "medium" | "hard" | null
Only where the subject has levels.
targetinteger | null
A target score, where one fits the subject (role-plays, and tutors that give a score).

Returns

201 The assignment, with every learner it was set for. data is AssignmentWithLearners.

Fields of data

idstringrequired
Assignment id (asg_…).
pattern `^asg_.*`
subjectIdstringrequired
The subject it is in (sub_…; bare for keys on 2026-07-08).
unitIdstring | nullrequired
The class or team it was set for (everyone in it and below); null when set for named learners.
titlestringrequired
instructionsstring | nullrequired
skillsstring[]required
The subject's skill ids it covers.
focusAssignmentFocus | nullrequired
The topic, question set or scenario; null: anything in the subject.
difficulty"easy" | "medium" | "hard" | nullrequired
The level a session must be at, or harder; null: any.
targetinteger | nullrequired
The score (1-100) a session must reach; null: none.
minutesinteger | nullrequired
Minutes of counting sessions it asks for; null: one counting session.
dueAtstring (date-time) | nullrequired
createdByobjectrequired
Who set it: a member, an API key, or the tutor's own suggestion.
- kind"member" | "api_key" | "tutor"required
- idstring | nullrequired
  The person (usr_…) or the API key (key_…); null for the tutor.
countsobjectrequired
- assignedintegerrequired
- startedintegerrequired
- completedintegerrequired
- overdueintegerrequired
  Not completed by the due date.
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.
learnersobject[]required
Every learner it was set for, with where they are.
- personIdstringrequired
  Person id (usr_…).
  pattern `^usr_.*`
- state"assigned" | "started" | "completed" | "overdue"required
  assigned, started, completed, or overdue (not completed by the due date).
- minutesDoneintegerrequired
  Minutes spent in sessions that count towards it.
- startedAtstring (date-time) | nullrequired
- completedAtstring (date-time) | nullrequired

Errors

invalid_request unauthorized forbidden upgrade_required not_found conflict idempotency_conflict idempotency_in_progress rate_limited server_error capacity

Events

assignment.created

Request

curl -X POST "https://app.zentiqai.com/v1/assignments" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "subjectId": "…",
  "title": "…"
}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.createAssignment({
  subjectId: "…",
  title: "…",
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.create_assignment({
    "subjectId": "…",
    "title": "…",
})

Response

201 · JSON

{
  "data": {
    "id": "asg_cmfq2b7x10000abcd1234",
    "subjectId": "sub_cmfq2b7x10000abcd1234",
    "unitId": "unit_cmfq2b7x10000abcd1234",
    "title": "…",
    "instructions": "…",
    "skills": [
      "…"
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/assignments/{id}

Get an assignment

getAssignmentassignments:readread: 600/min per keySince 2026-10-01

With every learner it was set for and where they are (learners by id; their names are read with people:read).

Path parameters

idstringrequired
Assignment id (asg_…); the id without its prefix is accepted too.

Returns

200 The assignment. data is AssignmentWithLearners.

Fields of data

idstringrequired
Assignment id (asg_…).
pattern `^asg_.*`
subjectIdstringrequired
The subject it is in (sub_…; bare for keys on 2026-07-08).
unitIdstring | nullrequired
The class or team it was set for (everyone in it and below); null when set for named learners.
titlestringrequired
instructionsstring | nullrequired
skillsstring[]required
The subject's skill ids it covers.
focusAssignmentFocus | nullrequired
The topic, question set or scenario; null: anything in the subject.
difficulty"easy" | "medium" | "hard" | nullrequired
The level a session must be at, or harder; null: any.
targetinteger | nullrequired
The score (1-100) a session must reach; null: none.
minutesinteger | nullrequired
Minutes of counting sessions it asks for; null: one counting session.
dueAtstring (date-time) | nullrequired
createdByobjectrequired
Who set it: a member, an API key, or the tutor's own suggestion.
- kind"member" | "api_key" | "tutor"required
- idstring | nullrequired
  The person (usr_…) or the API key (key_…); null for the tutor.
countsobjectrequired
- assignedintegerrequired
- startedintegerrequired
- completedintegerrequired
- overdueintegerrequired
  Not completed by the due date.
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.
learnersobject[]required
Every learner it was set for, with where they are.
- personIdstringrequired
  Person id (usr_…).
  pattern `^usr_.*`
- state"assigned" | "started" | "completed" | "overdue"required
  assigned, started, completed, or overdue (not completed by the due date).
- minutesDoneintegerrequired
  Minutes spent in sessions that count towards it.
- startedAtstring (date-time) | nullrequired
- completedAtstring (date-time) | nullrequired

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/assignments/asg_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getAssignment("asg_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_assignment("asg_123")

Response

200 · JSON

{
  "data": {
    "id": "asg_cmfq2b7x10000abcd1234",
    "subjectId": "sub_cmfq2b7x10000abcd1234",
    "unitId": "unit_cmfq2b7x10000abcd1234",
    "title": "…",
    "instructions": "…",
    "skills": [
      "…"
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

PATCH/v1/assignments/{id}

Change an assignment

updateAssignmentassignments:writewrite: 120/min per keySince 2026-10-01

Its title, instructions, due date or minutes; null clears the instructions, the due date or the minutes. A due date already gone is refused. Who it is for and what counts towards it stay as set: delete it and set it again to change those.

Path parameters

idstringrequired
Assignment id (asg_…); the id without its prefix is accepted too.

Body

titlestring
1-120 characters
instructionsstring | null
null clears them.
dueAtstring | null
null clears it. A date already gone is refused.
minutesinteger | null
null clears it.

Returns

200 The assignment. data is AssignmentWithLearners.

Fields of data

idstringrequired
Assignment id (asg_…).
pattern `^asg_.*`
subjectIdstringrequired
The subject it is in (sub_…; bare for keys on 2026-07-08).
unitIdstring | nullrequired
The class or team it was set for (everyone in it and below); null when set for named learners.
titlestringrequired
instructionsstring | nullrequired
skillsstring[]required
The subject's skill ids it covers.
focusAssignmentFocus | nullrequired
The topic, question set or scenario; null: anything in the subject.
difficulty"easy" | "medium" | "hard" | nullrequired
The level a session must be at, or harder; null: any.
targetinteger | nullrequired
The score (1-100) a session must reach; null: none.
minutesinteger | nullrequired
Minutes of counting sessions it asks for; null: one counting session.
dueAtstring (date-time) | nullrequired
createdByobjectrequired
Who set it: a member, an API key, or the tutor's own suggestion.
- kind"member" | "api_key" | "tutor"required
- idstring | nullrequired
  The person (usr_…) or the API key (key_…); null for the tutor.
countsobjectrequired
- assignedintegerrequired
- startedintegerrequired
- completedintegerrequired
- overdueintegerrequired
  Not completed by the due date.
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.
learnersobject[]required
Every learner it was set for, with where they are.
- personIdstringrequired
  Person id (usr_…).
  pattern `^usr_.*`
- state"assigned" | "started" | "completed" | "overdue"required
  assigned, started, completed, or overdue (not completed by the due date).
- minutesDoneintegerrequired
  Minutes spent in sessions that count towards it.
- startedAtstring (date-time) | nullrequired
- completedAtstring (date-time) | nullrequired

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Events

assignment.updated

Request

curl -X PATCH "https://app.zentiqai.com/v1/assignments/asg_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.updateAssignment("asg_123", {});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.update_assignment("asg_123", {})

Response

200 · JSON

{
  "data": {
    "id": "asg_cmfq2b7x10000abcd1234",
    "subjectId": "sub_cmfq2b7x10000abcd1234",
    "unitId": "unit_cmfq2b7x10000abcd1234",
    "title": "…",
    "instructions": "…",
    "skills": [
      "…"
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

DELETE/v1/assignments/{id}

Delete an assignment

deleteAssignmentassignments:writewrite: 120/min per keySince 2026-10-01

Withdraws the work: it and every learner's state on it go. Sessions, results and reports stay.

Path parameters

idstringrequired
Assignment id (asg_…); the id without its prefix is accepted too.

Returns

200 Deleted. data is object.

Fields of data

deletedtruerequired
idstringrequired
Assignment id (asg_…).
pattern `^asg_.*`

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Events

assignment.deleted

Request

curl -X DELETE "https://app.zentiqai.com/v1/assignments/asg_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.deleteAssignment("asg_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.delete_assignment("asg_123")

Response

200 · JSON

{
  "data": {
    "deleted": true,
    "id": "asg_cmfq2b7x10000abcd1234"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

Assignments

List assignments

Query parameters

Returns

Errors

Request

Response

Set work

Body

Returns

Errors

Events

Request

Response

Get an assignment

Path parameters

Returns

Errors

Request

Response

Change an assignment

Path parameters

Body

Returns

Errors

Events

Request

Response

Delete an assignment

Path parameters

Returns

Errors

Events

Request

Response