Skip to main content

​
Directory API

The Directory API is part of Meitner’s RESTful API suite. It enables organizations to programmatically manage admin-controlled resources. Some example use cases include:
  • Managing schools and their properties
  • Creating and managing groups and group memberships
  • Creating and managing user types:
    • Employees
    • Guardians
    • Students
The API is organized around REST principles. It uses predictable, resource-oriented URLs, accepts JSON-encoded request bodies for POST and PATCH requests (when a body is required), and returns JSON-encoded responses. Query parameters can be used for pagination. Standard HTTP verbs and status codes are used throughout, and all requests require authentication.
Note: The Meitner API does not support bulk updates — you can modify only one object per request.

​
Endpoint

Meitner’s Directory API is available at: 
https://api.meitner.se/directory/v1
For testing and debugging, you can use our staging environment: 
https://api.staging.meitner.se/directory/v1

​
Authentication

All requests to the Meitner Directory API must be authenticated.
Free API Keys: All Meitner clients receive API keys at no extra cost. We believe you own your data and should have access to it through our APIs. Learn more about our pricing and API access.
Authentication is handled via two required headers:
  • Client-ID: Your public client identifier.
  • Client-Secret: A secret key tied to your client ID.
curl -H "Client-ID: your-client-id" -H "Client-Secret: your-client-secret" https://api.meitner.se/directory/v1/student
We are currently evaluating improvements to our authentication flow to enhance security and simplify integration. Future changes may include rotating secrets, OAuth support, or scoped access tokens.

​
Resource Structure

The Meitner API uses a consistent and straightforward structure for working with resources:
  • POST /student Creates a new student.
  • PATCH /student/:id Updates an existing student.
  • GET /student Lists all students. Supports limit and offset query parameters for pagination. See the Pagination section for more details.
  • GET /student/:id Retrieves a specific student by ID.
  • DELETE /student/:id Deletes a specific student.
  • POST /student/_search Supports advanced filtering using a type-safe JSON body. See the Search/Filtering section for more details.
Note: Not all resources support every method—for example, creation may not be allowed for read-only resources.
Some resources may also expose additional custom methods when needed.

​
Requests

​
Body

We aim to keep request bodies minimal, requiring as few fields as possible. When creating a resource (POST), default values are applied automatically where possible. You only need to provide values if you want to override the defaults. Nullable fields will typically default to null if not provided.

​
Updates

The Meitner API uses the PATCH method for updates, which allows partial updates. You only need to include the fields you want to change. We also differentiate between undefined and null values:
  • If a field is omitted from the request body, it is treated as undefined and left unchanged.
  • If a field is included with the value null, it will explicitly overwrite the existing value with null.

​
Example

Let’s say a student has the following data: 
{
  "name": "Alice",
  "email": "[email protected]"
}
If you want to update only the email: 
PATCH /student/123
Content-Type: application/json

{
  "email": "[email protected]"
}
Result: 
{
  "name": "Alice",
  "email": "[email protected]"
}
If you want to remove the email entirely: 
PATCH /student/123
Content-Type: application/json

{
  "email": null
}
Result: 
{
  "name": "Alice",
  "email": null
}

​
Arrays

For array fields, any update replaces the entire array:
  • Sending an array like ["id1", "id2"] will fully replace the existing values.
  • Sending an empty array ([]) or null will clear all existing values.
For example, a guardian’s studentIDs field will be fully overwritten if included in the request, regardless of its previous contents.

​
Responses

​
Body

When retrieving, creating, or updating a resource, the API returns the resource directly in the JSON body: 
{
  "name": "Alice",
  "email": ""
}
When the response includes multiple rows for a resource, the body returns a data field with an array: 
{
   "data": [
      {
         "name": "Alice",
         "email": ""
      }
   ]
}

​
Warnings

Coming soon.

​
Errors

Coming soon.

​
Status Codes

The Meitner API uses a fixed set of standard HTTP status codes to indicate the result of a request:
CodeMeaningDescription
200OKThe request succeeded and a response body is included.
201CreatedThe resource was successfully created.
204No ContentThe request succeeded but there’s no response body (commonly used for deletes).
400Bad RequestThe request was malformed or contained invalid parameters.
401UnauthorizedThe request is missing valid authentication credentials.
403ForbiddenAuthentication succeeded, but the user is not allowed to perform the operation.
404Not FoundThe requested resource or endpoint does not exist. This can happen if a resource ID is invalid or the route is unknown.
409ConflictThe request could not be completed due to a conflict, such as a resource with dependencies that prevent deletion.
422Unprocessable EntityThe request was well-formed but failed validation (e.g. invalid field format or constraints).
429Too Many RequestsThe rate limit has been exceeded. See the Rate Limiting section for more details.
500Internal Server ErrorAn unexpected error occurred on the server side.
Note: If a request fails, the response body typically includes an error object with more details.
If a 500 error occurs, Meitner staff is automatically alerted and will investigate the issue.