Worlds / Education

PowerSchool API

A local PowerSchool SIS with students, enrollments, sections, attendance codes and the gradebook. Test the school office agent that takes attendance, enrolls students and updates schedules.

Base path: /ws/v1
Auth: OAuth 2.0 client credentials bearer token, the world key
Endpoints: 16
Status: Active today

This reference previews the surface the PowerSchool world serves in the closed beta. Paths mirror the public PowerSchool API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_POWERSCHOOL_URL`	This world's origin followed by `/ws/v1`
`WORLDS_API_KEY`	The world key, accepted wherever PowerSchool expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_POWERSCHOOL_URL + "/ws/v1";

const res = await fetch(base + "/school/1/student?expansions=demographics", {
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
    Accept: "application/json",
  },
});

const { students } = await res.json();
console.log(students.student.length);

API reference

16 of 16

Students

Enrolled students and demographics.

GET/ws/v1/school/{school_id}/studentList students at a school
GET/ws/v1/student/{id}Get a student
POST/ws/v1/studentCreate a student
PUT/ws/v1/student/{id}Update a student

Fields · 5

`id`	integer	Student dcid
`local_id`	integer	Student number
`name`	object	First, middle and last name
`demographics`	object	Birth date, gender
`school_enrollment`	object	Grade level, entry date

Schools

Schools in the district.

GET/ws/v1/district/schoolList schools
GET/ws/v1/school/{id}Get a school
GET/ws/v1/school/{school_id}/termList terms

Fields · 5

`id`	integer	School dcid
`name`	string	School name
`school_number`	integer	School number
`low_grade`	integer	Lowest grade
`high_grade`	integer	Highest grade

Sections

Class sections and rosters.

GET/ws/v1/school/{school_id}/sectionList sections
GET/ws/v1/section/{id}Get a section
GET/ws/v1/section/{id}/section_enrollmentList section enrollments

Fields · 6

`id`	integer	Section dcid
`course_number`	string	Course number
`section_number`	string	Section
`staff_id`	integer	Teacher
`term_id`	integer	Term
`expression`	string	Period schedule

Attendance

Daily and period attendance.

GET/ws/v1/student/{id}/attendanceList student attendance
POST/ws/v1/attendanceRecord attendance
GET/ws/v1/attendance_codeList attendance codes

Fields · 5

`id`	integer	Attendance id
`studentid`	integer	Student
`att_date`	date	Date
`attendance_codeid`	integer	Code
`ccid`	integer	Section enrollment

Final grades

Stored grades per term.

GET/ws/v1/student/{id}/storedgradesList student stored grades
GET/ws/v1/section/{id}/finalgradeList section final grades
PUT/ws/v1/finalgrade/{id}Update a final grade

Fields · 6

`id`	integer	Grade id
`studentid`	integer	Student
`sectionid`	integer	Section
`storecode`	string	Term store code
`grade`	string	Letter grade
`percent`	number	Percent

Test workflow

Prepare. Select the PowerSchool setup for your workflow and review its starting records, including students, schools, sections.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

900101 marked tardy for period 2
900102 marked excused
900177 still absent, the note was for 900102
900104 still absent
No attendance changed for any past date

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · PowerSchool
version: 2
connector: powerschool
seed: powerschool-starter
mode: isolated
policy: >
  Update today's attendance from office notes. Change codes only for the
  student number on each note, mark late arrivals tardy, and leave anyone
  without a note absent.
tasks:
  - id: record-daily-attendance-with-the-right-codes
    prompt: Record daily attendance with the right codes
  - id: enroll-new-students-into-sections
    prompt: Enroll new students into sections
  - id: fix-schedule-conflicts-and-drop-sections
    prompt: Fix schedule conflicts and drop sections
expected:
  - 900101 marked tardy for period 2
  - 900102 marked excused
  - "900177 still absent, the note was for 900102"
  - 900104 still absent
  - No attendance changed for any past date
scenarios:
  - plugin-token-expires
  - section-full
  - paged-query

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`plugin-token-expires`	The OAuth token returns 401 mid run
`section-full`	Enrollment is rejected because the section is at max
`paged-query`	A large student query returns results in pages
`attendance-locked`	Writing attendance for a past date is rejected

Starting data

Start each run from the same records and relationships. The overview below describes the PowerSchool starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
students	400 fake students across grades 9 to 12
sections	60 sections with periods and room numbers
enrollments	Course enrollments with entry and exit dates
attendance	Codes for present, absent, tardy and excused
gradebook	Final grades for the current term

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Students records

Students

Enrolled students and demographics.

Field	Type	Meaning / relationship
`id`	integer	Student dcid
`local_id`	integer	Student number
`name`	object	First, middle and last name
`demographics`	object	Birth date, gender
`school_enrollment`	object	Grade level, entry date

json · illustrative record shape

{
  "id": 1,
  "local_id": 1,
  "name": {},
  "demographics": {},
  "school_enrollment": {}
}

See students operations

Schools records

Schools

Schools in the district.

Field	Type	Meaning / relationship
`id`	integer	School dcid
`name`	string	School name
`school_number`	integer	School number
`low_grade`	integer	Lowest grade
`high_grade`	integer	Highest grade

json · illustrative record shape

{
  "id": 1,
  "name": "<School name>",
  "school_number": 1,
  "low_grade": 1,
  "high_grade": 1
}

See schools operations

Sections records

Sections

Class sections and rosters.

Field	Type	Meaning / relationship
`id`	integer	Section dcid
`course_number`	string	Course number
`section_number`	string	Section
`staff_id`	integer	Teacher
`term_id`	integer	Term
`expression`	string	Period schedule

json · illustrative record shape

{
  "id": 1,
  "course_number": "<Course number>",
  "section_number": "<Section>",
  "staff_id": 1,
  "term_id": 1,
  "expression": "<Period schedule>"
}

See sections operations

Attendance records

Attendance

Daily and period attendance.

Field	Type	Meaning / relationship
`id`	integer	Attendance id
`studentid`	integer	Student
`att_date`	date	Date
`attendance_codeid`	integer	Code
`ccid`	integer	Section enrollment

json · illustrative record shape

{
  "id": 1,
  "studentid": 1,
  "att_date": "<Date>",
  "attendance_codeid": 1,
  "ccid": 1
}

See attendance operations

Final grades records

Final grades

Stored grades per term.

Field	Type	Meaning / relationship
`id`	integer	Grade id
`studentid`	integer	Student
`sectionid`	integer	Section
`storecode`	string	Term store code
`grade`	string	Letter grade
`percent`	number	Percent

json · illustrative record shape

{
  "id": 1,
  "studentid": 1,
  "sectionid": 1,
  "storecode": "<Term store code>",
  "grade": "<Letter grade>",
  "percent": 1
}

See final grades operations

See the PowerSchool world in the catalog