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

# Public API

> Integrating the Ardoise marketplace (schools, tutors, job adverts) into your own site or system.

The public API lets an integration read authorised public profiles and submit leads with a key issued to an authorised account. The client needs neither the Firebase SDK nor a user browser session for each request; the key owner still needs an account and must respect its scopes/country.

<Info>
  Published profile fields remain subject to the key's country and scope checks. Private data and unpublished contact details are excluded. Use this server entry point with revocable keys and usage tracking; do not assume anonymous or direct Firestore access.
</Info>

## Getting a key

<Steps>
  <Step title="Create a developer account">
    Sign up at [saas.ardoiseeduc.com](https://saas.ardoiseeduc.com/register) with the **Developer** role.
  </Step>

  <Step title="Generate a key">
    From the **Developer Space**, **API keys** section: tick the scopes you need, then generate a test key (`sk_test_...`) or a production key (`sk_live_...`).
  </Step>

  <Step title="Authenticate your requests">
    Send the key in the `Authorization` header of every request:

    ```bash theme={null}
    curl -H "Authorization: Bearer sk_live_..." https://api.ardoiseeduc.com/api/public/schools
    ```
  </Step>
</Steps>

<Note>
  A school that wants to display **its own** profile or **its own** job adverts on its site does not need a developer account: the founder generates a dedicated key from **API Integrations** on their dashboard - see [School API key](#school-api-key-scope-schoolprofile) below.
</Note>

## Scopes

A production key requires identity verification, technical certification and partner approval through the developer journey. A sandbox test key does not authorise production access. See [Developer Academy and certification](/en/plateforme/partenaires-certifies#developer-academy-and-certification).

| Scope | Gives access to |
| - | - |
| `marketplace:read` | Reading published schools, tutors, job adverts and certified partners, filterable by country (see [Available countries](#available-countries)) |
| `leads:write` | Submitting a lead (school or candidate) to the Ardoise CRM |
| `school:profile` | Reading the profile of **a single** school (a key generated by that school itself) |
| `support:access` | Reserved for [certified partners](/en/plateforme/partenaires-certifies) - access to the server/backup status of a school that has explicitly granted that access |

An invalid or revoked key, or one lacking the required scope, receives `401`/`403` with a message explaining which.

## Available countries

The `country` parameter accepts the code or exact French name. Developer keys are restricted to the country authorised server-side. Omitting the parameter retains that scope; requesting another country or supplying an out-of-scope profile identifier is refused. The list below is technical reference, not evidence that every offering/payment is available there. Ardoise School is not offered in Austria.

| Code | Country |
| - | - |
| `BEN` | Benin |
| `BFA` | Burkina Faso |
| `CMR` | Cameroon |
| `CAF` | Central African Republic |
| `COM` | Comoros |
| `COG` | Congo |
| `COD` | DRC |
| `CIV` | Côte d'Ivoire |
| `GAB` | Gabon |
| `GIN` | Guinea |
| `GNB` | Guinea-Bissau |
| `GNQ` | Equatorial Guinea |
| `MLI` | Mali |
| `NER` | Niger |
| `SEN` | Senegal |
| `TCD` | Chad |
| `TGO` | Togo |
| `AUT` | Austria |

<Tip>
  This list is also available through the API (see `GET /api/public/countries` below), which is handy for building a country selector without copying it by hand.
</Tip>

## Endpoints

<Note>
  Base URL: `https://api.ardoiseeduc.com`
</Note>

### `GET /api/public/countries`

Returns the list of the 18 countries above (`{ "data": [{ "code": "BEN", "name": "Bénin" }, ...] }`). No key required - this is static reference data, not marketplace data.

### `GET /api/public/schools`

Lists the schools registered on the marketplace.

**Scope required:** `marketplace:read`

| Parameter | Description |
| - | - |
| `country` | Code or French name - see [Available countries](#available-countries) - optional, otherwise the authorised country |
| `limit` | Maximum number of results (default 50, max 200) |

```json theme={null}
{
  "data": [
    { "id": "abc123", "name": "École Les Palmiers", "city": "Cotonou", "country": "Bénin", "description": "...", "image": "https://..." }
  ]
}
```

### `GET /api/public/schools/:schoolId`

A public institution profile within the `marketplace:read` key's authorised country, or the specific institution of a `school:profile` key. The requested identifier still undergoes country checks; institutes also use public profiles without becoming School tenants.

### `GET /api/public/teachers`

Lists the marketplace's independent tutors. Same `country`/`limit` parameters as `/schools`.

<Note>
  This route exposes authorised public fields, not private contact details, contracts or financial records. Contact and booking use authorised journeys; Marketplace fees and payments cannot be inferred from this public result.
</Note>

### `GET /api/public/jobs`

Lists open job adverts, filterable by `country` and/or `schoolId`.

**Scope required:** `marketplace:read`

### `GET /api/public/partners`

Lists approved [certified partners](/en/plateforme/partenaires-certifies), filterable by `country`.

**Scope required:** `marketplace:read`

```json theme={null}
{
  "data": [
    { "id": "uid123", "publicName": "Jean Dupont", "bio": "...", "specialties": ["Installation", "Maintenance serveur"], "country": "Bénin" }
  ]
}
```

### `POST /api/public/leads`

Submits a lead (an interested school or a teacher candidate) into the Ardoise sales pipeline, so that a member of the team can follow up.

**Scope required:** `leads:write`

```json theme={null}
{
  "type": "school_prospect",
  "name": "Jean Dupont",
  "contactEmail": "jean@example.com",
  "contactPhone": "+229 90 00 00 00",
  "country": "Bénin",
  "message": "Intéressé par une démo pour notre établissement."
}
```

`type` is either `school_prospect` or `candidate`. `name` is required, along with `contactEmail` or `contactPhone` (at least one of the two).

## Support access (`support:access` scope)

Reserved for [certified partners](/en/plateforme/partenaires-certifies) to whom a founder has explicitly granted access - see that page for how a founder grants and revokes that access from their dashboard. These routes proxy to the school's own Django installation (never to data stored on the Platform side) and answer `403` if no active grant covers the school or the scope requested.

**Scope required:** `support:access`

### `GET /api/support/schools/:schoolId/health`

```json theme={null}
{ "status": "ok" }
```

### `GET /api/support/schools/:schoolId/backupStatus`

```json theme={null}
{
  "isConfigured": true,
  "isEnabled": true,
  "lastBackup": { "status": "success", "date": "2026-07-28T02:00:00Z", "error": null }
}
```

### `POST /api/support/schools/:schoolId/backupTrigger`

Triggers an immediate backup. Response `{ "success": true, "message": "..." }` or `{ "success": false, "error": "..." }`.

<Warning>
  These three routes are strictly limited to server and backup status - never to grades, accounting or pupil records, and they open no system access to the machine (no SSH, no console).
</Warning>

## School API key (scope `school:profile`)

From **API Integrations** on the founder dashboard, a school can generate its own key, limited to its own profile (`GET /api/public/schools/:itsOwnId`) and its own job adverts. That key can read nothing about another school, and gives access to no grade, finance or pupil data - only the same information already public on the marketplace.

<Warning>
  The public API does not and will not expose a school's grades, accounting or pupil records without a consent framework far broader than these keys - this is not a temporary omission, it is a deliberate limit.
</Warning>

## Current limitations

* No strict rate limiting (no dedicated infrastructure yet) - abusive use is monitored through the request counter shown in the **Developer Space**, and a key can be revoked at any time.
* Webhooks (real-time notifications) are configurable from the **Developer Space** but do not yet fire automatically on real events - only manual testing works today.

## See also

<CardGroup cols={2}>
  <Card title="MCP server" icon="plug" href="/en/plateforme/mcp">
    Use the same public functions with a Model Context Protocol client.
  </Card>

  <Card title="Certified partners" icon="user-check" href="/en/plateforme/partenaires-certifies">
    Become a certified partner, or grant support access to a partner from your school.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.