Skip to main content

API Usage

Quick start: calling the API​

Prerequisites​

You need at least a user account to get started. See creating your first user.

Create an access token​

To call the API, you need a valid JWT access token. You can obtain one by calling the authentication endpoint.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "username": "john.doe", "password": "john.doe.0123456789" }' \
  http://localhost:8080/api/auth/login

If the credentials are valid, the response contains an access token:

{
  "access_token": "<token>"
}

This token can be included in all subsequent API calls using the HTTP Authorization header:

Authorization: Bearer <token>

Call a first API endpoint​

Start with a simple action that does not require parameters.

curl -H "Authorization: Bearer <your_token>" http://localhost:8080/api/config/inspect_config

If everything is correctly configured:

  • the request succeeds
  • the server returns a response
  • the token is validated

This confirms that authentication and API access are working.

Passing parameters​

Some actions expect parameters.

Parameters can be passed either as query parameters or as a JSON body.

Example with a JSON body:

curl -X POST \
     -H "Authorization: Bearer <your_token>" \
     -H "Content-Type: application/json" \
     -d '{ "from": "https://gitlab.com/opendatafrance/scdl/menus-collectifs/-/raw/master/schema.json" }' \
     http://localhost:8080/api/model/import

The response contains the result of the action execution.

Errors are returned with a semantic HTTP status code and a structured error body.

How the API works​

Medatarun API allows you to trigger the same actions as the server itself through HTTP calls. It is designed for automation, integration, and tooling.

The API is action-based. Each HTTP call represents an explicit operation executed by Medatarun. There is no generic CRUD layer or resource abstraction.

All API endpoints are exposed under the /api base path.

An action is called using the following URL structure:

/api/<actionGroup>/<action>

For example, calling an action named inspect_config in the config group results in:

/api/config/inspect_config

Both GET and POST methods are accepted for action calls. The server does not distinguish between them semantically. Use POST when you need to send a request body.

Request parameters are provided as follows:

  • simple parameters can be passed as query parameters
  • when an action expects structured input, parameters are passed as a JSON request body

If no body is provided, an empty payload is assumed.

tip

For your application integrations, POST with systematic JSON body is the preferred choice. GET is available as a convenience for simple curl calls

API calls require authentication, except for API discovery and a few public actions (login, auth, etc.).

Requests must include a valid JWT access token using the standard HTTP header:

Authorization: Bearer <access_token>

The API accepts any valid OIDC token, including tokens issued by an external identity provider, as long as the provider is configured in Medatarun. See configuration

There is no refresh mechanism at the API level. Tokens are expected to be managed by the client.

To verify that your token is valid and that the API is reachable, you can start with a simple call that does not require parameters.

Example:

GET /api/config/inspect_config

If authentication succeeds, the server returns the result of the action directly.

Most actions return JSON data. Some actions intentionally return plain text responses. This is expected and depends on the action semantics.

  • On success, the HTTP status code is 200 OK.
  • On error, the server returns a semantic HTTP status code (400, 401, 403, 404, 500, etc.). The response body follows the application/problem+json format and describes the error.

API Documentation​

The API is self-describing. You can find its documentation in several places.

User interface​

When in the user interface, with the technical mode active, on the main menu, choose Action Runner. You will be able to see the full documentation, including:

  • available action groups
  • action names
  • parameters and their types
  • whether parameters are optional
  • security rules and how they apply

Also, you will be able to execute actions directly with your own credentials.

CLI​

Using the medatarun help command in a terminal, all action groups, actions names, parameters, types, optional or not are described in the style of a man page.

OpenAPI format and Swagger​

You can retrieve the API description with:

GET /api

This endpoint is public and returns a minimal, OpenAPI-compatible description of available actions, payload fields and required parameters.

In practice, OpenAPI alone is not enough to fully understand and use this API. It documents endpoints and payload shapes, but not the full action intent, constraints, and usage context.

For complete functional documentation (intent, constraints, examples, context), use:

You can load the /api response directly in Swagger Editor: https://editor.swagger.io/