fepli
deen
DevelopersREST API

Quickstart

This guide takes you from nothing to an authenticated call in five minutes. You'll find your endpoint, list the public offers, get a token, check what it can do and then use it.

  1. 1no tokenFind your endpointbase URL
  2. 2no tokenMake a public requestGET /offers
  3. 3in the adminGet a tokenFEPLI_TOKEN
  4. 4with the tokenCheck who you areGET /me
  5. 5with the tokenUse the tokenGET /search

1. Find your endpoint

Every organisation runs its own fepli, so each has its own API endpoint.

Anatomy of a request URLWhere the API sits
https://example.fepli.euthe admin’s host/apithe API prefix/offersthe path in these docs

By default, the API sits on the admin’s host under /api. If you open the admin at https://example.fepli.eu/admin, the API is at https://example.fepli.eu/api.

Super admins see the endpoint under Einstellungen → Integrationen → API, in the Endpunkt row. On a single-tenant installation it shows just /api, which means the admin's own host.

All examples in this documentation use https://example.fepli.eu/api as the base URL. Paths such as /offers are relative to it.

On the same settings page, super admins can switch the whole API on or off with Schnittstelle aktiv, and Öffentlicher Zugriff decides whether the published offers can be read without a token. A switched-off API answers every request with 404.

Einstellungen → Integrationen → APIWhat the two switches decide
GET /offerswithout a token200the published offersGET /offerswith a token200what its roles allow

2. Make a public request

The published offers of the editions that are online can be read without a token, as long as public access is switched on. Try it:

GET/offers
curl https://example.fepli.eu/api/offers

You get back a JSON array of offers. If you only want to show offers on a website, you can stop here and read Offers on your website.

3. Get a token

Everything else needs a token. There are two kinds:

A personal access tokenquickest to try

Acts as you, with your roles. Create one in the admin: open your user menu, choose Passwort ändern, and on the Sicherheit page go to API-Tokens → Neuer API-Token.

A service account tokenfor integrations

Acts as a service account, a machine identity with only the roles you give it. Use one for anything that keeps running, such as an integration or a reporting job. Super admins create them under Einstellungen → Integrationen → API → Service-Accounts.

When you create a token, choose Nur lesen (read-only) unless you need to change data, and give it an expiry date. The token is shown once. Copy it and keep it somewhere safe, then put it into an environment variable for the examples below:

export FEPLI_TOKEN='svc-…'

4. Check who you are

Send the token as a bearer token in the Authorization header. The first call to make is GET /me: it tells you who the token belongs to, which roles it has and whether it can write.

GET/me
curl https://example.fepli.eu/api/me \
  -H "Authorization: Bearer $FEPLI_TOKEN"
ResponseSelect a field
{
}
rolesThe roles that decide which endpoints the token can use.

A 401 here means the token is wrong, expired, or belongs to a disabled service account. See Authentication.

5. Use the token

With a token, the offers endpoint returns more than the published offers, and the other endpoints open up.

Same endpoint, two answersWhat a token opens up
Without a tokenGET /offersthe published offers of the editions that are onlineother endpoints401
With a tokenGET /offersevery offer you may see in the admin, drafts included, along with the internal fieldsother endpointsopen up according to your roles

For example, you can search everything your roles let you see:

Search

curl "https://example.fepli.eu/api/search?q=Fahrradtour" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

{
  "query": "Fahrradtour",
  "offers": [
    {
      "uuid": "0192a4f1-6e3b-7c85-b1d2-8f4e6a9c3b03",
      "name": "Fahrradtour durch den Stadtpark",
      "alias": "fahrradtour-durch-den-stadtpark"
    }
  ],
  "editions": [],
  "participants": [],
  "accounts": [],
  "hosts": [],
  "receipts": []
}

Every reference in a response carries a uuid. Use it to fetch the full record, for example GET /offers/{uuid}.

What's next?

  • Authentication: token types, scopes and what happens when a token is refused
  • Permissions: which roles unlock which endpoints
  • Conventions: identifiers, dates, amounts, filters and how PATCH works
  • Offers: the reference for the most-used resource

Was this page helpful?