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

# Partner API overview

> Assign Quippy tests to your own users and get results back — from your platform.

The Partner API lets your platform assign Quippy tests to your users and
receive their results, without your users ever creating a Quippy account
separately. It's built for products that embed Quippy assessments into their
own flow — an LMS, a certification portal, a recruitment tool.

## The flow

```mermaid theme={null}
sequenceDiagram
    participant You as Your server
    participant Browser as Student's browser
    participant Quippy as Quippy
    You->>Quippy: GET /partner/v1/tests
    Quippy-->>You: available tests
    You->>Quippy: POST /partner/v1/assignments
    Quippy-->>You: { assignmentId, startUrl }
    Browser->>Quippy: student opens startUrl
    Note over Browser,Quippy: signed in automatically,<br/>lands on the assigned test
    Quippy--)You: webhooks (started, completed, graded)
    Browser->>You: "Return to <you>" → your callbackUrl
```

1. **List tests** — fetch the tests published to your institution.
2. **Assign** — create an assignment for one of your users. You get back an
   `assignmentId` and a signed `startUrl`.
3. **Start** — your user opens the `startUrl`. They're signed in automatically
   (no password, no separate registration) and land directly on the test.
4. **Results** — you receive [webhooks](/webhooks/events) as the student
   starts, submits, and is graded — each carrying your `externalUserId` and
   `partnerAssignmentId` so you can correlate exactly. You can also poll
   `GET /partner/v1/assignments/{id}`.
5. **Return** — when the student finishes, a **"Return to \<you>"** button
   sends them back to the `callbackUrl` you provided.

## What you'll need

<CardGroup cols={2}>
  <Card title="An API key" icon="key" href="/partner-api/authentication">
    Server-to-server credential, created in the admin portal.
  </Card>

  <Card title="A callback domain" icon="link" href="/partner-api/authentication">
    Allowlist the domain your students return to.
  </Card>

  <Card title="Published tests" icon="list-check" href="/partner-api/assign-a-test">
    We curate which of your tests are assignable — ask your Quippy contact.
  </Card>

  <Card title="A webhook endpoint" icon="webhook" href="/webhooks/setup">
    Recommended, for real-time result delivery.
  </Card>
</CardGroup>

## Conventions

* Base URL: `https://api-sg.quippy-lab.com`
* All requests and responses are JSON.
* All timestamps are ISO 8601 UTC.
* All IDs are **opaque strings** — never parse or depend on their format.
* The API is versioned in the path (`/partner/v1/…`). New fields and events
  may be added without a version bump, so parse tolerantly.

<Note>
  This is a server-to-server API. Your API key must never appear in browser
  or mobile code — see [Authentication](/partner-api/authentication).
</Note>