> ## Documentation Index
> Fetch the complete documentation index at: https://fayneos.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add, List, and Remove Students in Your Academy API

> List, add, retrieve, and remove students in your academy. Supports bulk course enrollment on creation and detailed progress tracking per student.

The students endpoints let you manage the people who learn in your academy. You can list all students with pagination, add new students and optionally enroll them in courses at the same time, retrieve a single student's profile and detailed progress, and remove a student from your academy. All endpoints require your API key in the `Authorization` header. See [Authentication](/api-reference/authentication).

***

## List students

Returns a paginated list of active students in your academy.

```text theme={null}
GET /api/v1/students
```

### Query parameters

<ParamField query="limit" default="50" type="number">
  Number of students to return. Minimum `1`, maximum `100`.
</ParamField>

<ParamField query="offset" default="0" type="number">
  Number of students to skip before returning results. Use with `limit` for pagination.
</ParamField>

### Response fields

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="students" type="object[]" required>
      Array of student objects, ordered by `joined_at` descending.

      <Expandable title="student properties" defaultOpen>
        <ResponseField name="id" type="string" required>
          UUID of the student's user account.
        </ResponseField>

        <ResponseField name="email" type="string" required>
          Student's email address.
        </ResponseField>

        <ResponseField name="name" type="string">
          Student's display name. May be `null` if not set.
        </ResponseField>

        <ResponseField name="avatar_url" type="string">
          URL of the student's avatar image. May be `null`.
        </ResponseField>

        <ResponseField name="joined_at" type="string" required>
          ISO 8601 timestamp of when the student joined the academy.
        </ResponseField>

        <ResponseField name="courses_enrolled" type="number" required>
          Number of active course enrollments.
        </ResponseField>

        <ResponseField name="enrollments" type="object[]" required>
          Array of active enrollment summaries.

          <Expandable title="enrollment properties">
            <ResponseField name="id" type="string" required>
              UUID of the enrollment record.
            </ResponseField>

            <ResponseField name="course_id" type="string" required>
              UUID of the enrolled course.
            </ResponseField>

            <ResponseField name="enrolled_at" type="string" required>
              ISO 8601 timestamp of enrollment.
            </ResponseField>

            <ResponseField name="completed_at" type="string">
              ISO 8601 timestamp of completion. `null` if not yet completed.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object" required>
      <Expandable title="properties" defaultOpen>
        <ResponseField name="total" type="number" required>
          Total number of students in the academy.
        </ResponseField>

        <ResponseField name="limit" type="number" required>
          The `limit` value used for this request.
        </ResponseField>

        <ResponseField name="offset" type="number" required>
          The `offset` value used for this request.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Example request

```bash theme={null}
curl "https://yourname.fayneos.com/api/v1/students?limit=10&offset=0" \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Example response

```json theme={null}
{
  "data": {
    "students": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "email": "alex@example.com",
        "name": "Alex Rivera",
        "avatar_url": "https://cdn.example.com/avatars/alex.jpg",
        "joined_at": "2025-03-15T09:22:00Z",
        "courses_enrolled": 2,
        "enrollments": [
          {
            "id": "e1f2a3b4-c5d6-7890-efab-123456789abc",
            "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "enrolled_at": "2025-03-15T09:22:00Z",
            "completed_at": null
          }

        ]
      }
    ],
    "pagination": {
      "total": 42,
      "limit": 10,
      "offset": 0
    }
  }
}
```

***

## Add a student

Adds a new student to your academy and optionally enrolls them in one or more courses in a single request.

```text theme={null}
POST /api/v1/students
```

### Body parameters

<ParamField body="email" type="string" required>
  Email address of the student. Must be a valid email format.
</ParamField>

<ParamField body="name" type="string">
  Display name for the student. Maximum 200 characters. Optional.
</ParamField>

<ParamField body="course_ids" type="string[]">
  Array of course UUIDs to enroll the student in. Maximum 50 course IDs per request. Each course must be published. Optional. Creates a permanent enrollment per course.
</ParamField>

<ParamField body="list_ids" type="string[]">
  Array of [list](/api-reference/lists) UUIDs to add the student to. Maximum 50 per request. Each list must exist in this academy, or the request returns `400 invalid_lists`. Use `list_ids` for cohort or tier access you may want to revoke later, and `course_ids` for a permanent per-course grant. Optional.
</ParamField>

<ParamField body="send_welcome_email" default="true" type="boolean">
  Whether to send the magic-link welcome email to the new student. Set to `false` for silent imports. Optional.
</ParamField>

### Response fields

Returns the newly created student with a `201` status code. The response contains `id`, `email`, `name`, a `membershipStatus` field (`created` or `reactivated`), and an `enrollments` array whose items have `id`, `course_id`, and `course_title`. This is a smaller object than the list endpoint's student: it does not include `avatar_url`, `joined_at`, or `courses_enrolled`. Adding a student who is already an active member of the academy returns `409 already_exists`.

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://yourname.fayneos.com/api/v1/students \
    -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "jamie@example.com",
      "name": "Jamie Chen",
      "course_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://yourname.fayneos.com/api/v1/students', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'jamie@example.com',
      name: 'Jamie Chen',
      course_ids: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890']
    })
  });
  const { data } = await response.json();
  ```
</CodeGroup>

***

## Get a student

Returns the full profile and enrollment detail for a single student, including per-course progress.

```text theme={null}
GET /api/v1/students/:studentId
```

### Path parameters

<ParamField path="studentId" type="string" required>
  UUID of the student. Must be a valid UUID or the request returns a `400`.
</ParamField>

### Response fields

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string" required>
      UUID of the student's user account.
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Student's email address.
    </ResponseField>

    <ResponseField name="name" type="string">
      Student's display name. May be `null`.
    </ResponseField>

    <ResponseField name="avatar_url" type="string">
      URL of the student's avatar image. May be `null`.
    </ResponseField>

    <ResponseField name="joined_at" type="string" required>
      ISO 8601 timestamp of when the student joined the academy.
    </ResponseField>

    <ResponseField name="enrollments" type="object[]" required>
      Array of active enrollments with full progress detail, ordered by `enrolled_at` descending.

      <Expandable title="enrollment properties" defaultOpen>
        <ResponseField name="id" type="string" required>
          UUID of the enrollment record.
        </ResponseField>

        <ResponseField name="course_id" type="string" required>
          UUID of the enrolled course.
        </ResponseField>

        <ResponseField name="course_title" type="string" required>
          Display title of the course.
        </ResponseField>

        <ResponseField name="course_slug" type="string" required>
          URL-safe slug of the course.
        </ResponseField>

        <ResponseField name="enrolled_at" type="string" required>
          ISO 8601 timestamp of enrollment.
        </ResponseField>

        <ResponseField name="completed_at" type="string">
          ISO 8601 timestamp of course completion. `null` if not yet completed.
        </ResponseField>

        <ResponseField name="total_lessons" type="number" required>
          Total number of published lessons in the course.
        </ResponseField>

        <ResponseField name="completed_lessons" type="number" required>
          Number of lessons the student has completed.
        </ResponseField>

        <ResponseField name="progress" type="number" required>
          Completion percentage from `0` to `100`, rounded to the nearest integer.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Example request

```bash theme={null}
curl https://yourname.fayneos.com/api/v1/students/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Example response

```json theme={null}
{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "email": "alex@example.com",
    "name": "Alex Rivera",
    "avatar_url": "https://cdn.example.com/avatars/alex.jpg",
    "joined_at": "2025-03-15T09:22:00Z",
    "enrollments": [
      {
        "id": "e1f2a3b4-c5d6-7890-efab-123456789abc",
        "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "course_title": "Cold Outreach Mastery",
        "course_slug": "cold-outreach-mastery",
        "enrolled_at": "2025-03-15T09:22:00Z",
        "completed_at": null,
        "total_lessons": 12,
        "completed_lessons": 5,
        "progress": 42
      }
    ]
  }
}
```

***

## Remove a student

Removes a student from your academy. This revokes all of their course enrollments and deletes all of their lesson progress, and cannot be undone. The student's Fayne account itself is not deleted; they are only removed from this academy.

```text theme={null}
DELETE /api/v1/students/:studentId
```

### Path parameters

<ParamField path="studentId" type="string" required>
  UUID of the student to remove.
</ParamField>

<Warning>
  Removing a student deletes all of their progress data in this academy and revokes access to every course. This cannot be reversed. Their Fayne account is not deleted.
</Warning>

### Response fields

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="removed" type="boolean" required>
      Always `true` when the operation succeeds.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example request

```bash theme={null}
curl -X DELETE \
  https://yourname.fayneos.com/api/v1/students/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Example response

```json theme={null}
{
  "data": {
    "removed": true
  }
}
```