Artesa API

Appearance

Getting Started with Artesa API ​

Artesa provides a powerful API that allows you to interact with your data in a flexible and efficient way. This documentation will guide you through the process of getting started with the Artesa API, including authentication, making requests, and handling responses.

Getting Started ​

To get started with the Artesa API, follow these steps:

  1. Login: If you're an admin, sign in. If you don't have an account yet, you can sign up for a free trial.
  2. Settings: Go to the settings page and create a new API key or copy an existing one. This key will be used to authenticate your requests.
  3. API Documentation: Familiarize yourself with the API documentation. The documentation is organized by version and includes detailed information about each endpoint, including request and response formats.
  4. Make Requests: Use your API key to make requests to the API. You can use tools like Postman or curl to test the endpoints.
  5. Handle Responses: The API will return responses in JSON format. Make sure to handle these responses appropriately in your application.
  6. Explore the API: The API is designed to be flexible and powerful. Explore the different endpoints and see how they can be used to interact with your data.

Base URL ​

All endpoints are served under:

https://api.artesa.de

Every endpoint is versioned in its path, for example https://api.artesa.de/v2/customers.

A staging environment is available at https://api-staging.artesa.dev. Its data may be out of date and it can contain unreleased changes — use it for testing only.

Localization ​

🇩🇪 Deutschland ​

  • assignments: Auftrag
  • assignment-types: Auftragstyp
  • assignment-events: Arbeitsschritt
  • assignment-event-groups: Arbeitsschrittgruppe
  • assignment-status-types: Auftragsstatus
  • customers: Kunde
  • roles: Benutzerrolle
  • users: Benutzer/Mitarbeiter

🇮🇹 Italia ​

  • assignments: Ordine
  • assignment-types: Tipo ordine
  • assignment-events: Fase di lavoro
  • assignment-event-groups: Gruppo
  • assignment-status-types: Stato ordine
  • customers: Cliente
  • roles: Ruolo utente
  • users: Dipendente

Authorization ​

To access the Artesa API, you need to include your API key in the Authorization header of your requests. The format should be:

Authorization: Bearer YOUR_API_KEY

Check the Samples on each endpoints documentation page for examples of how to include the API key in your requests.

Pagination ​

List endpoints are paginated. Two query parameters control the page:

  • page — zero-based page index (default 0).
  • size — number of items per page (default 10, maximum 20).

For example, GET /v2/customers?page=2&size=20 returns the third page of 20 customers.

Every list response is wrapped in a pagination envelope:

json
{
  "page": 0,
  "pages": 5,
  "size": 10,
  "items": [
    /* ... */
  ]
}
  • page — the current page index.
  • pages — the total number of pages available.
  • size — the page size used.
  • items — the array of results for this page.

Rate limits ​

Each company has one budget, shared by all its calls:

  • 800 points per minute: a read costs 1 point, a create, patch or delete 3, and include=customAttributes 1 more.
  • 5 calls at once.

Every response says where you stand: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, when the budget refills in epoch seconds. Over it, the API answers 429 Too Many Requests with Retry-After in seconds: wait that long, then repeat the call.

To stay within it, subscribe to webhooks instead of polling, sync by updatedAt[$gt]=<your last sync> instead of reading everything again, and read pages of size=20 one after another.

INFO

For now, calls over the budget are still served. The changelog announces when they are answered with 429.

Errors ​

The API uses standard HTTP status codes. On error, the response body is JSON with a consistent shape:

json
{
  "name": "BadRequest",
  "message": "Invalid query: \"createdAt\": Expected a valid ISO 8601 date-time string",
  "code": 400
}
  • name — a short error identifier (e.g. BadRequest, NotAuthenticated, NotFound).
  • message — a human-readable description of what went wrong.
  • code — the HTTP status code.

The most common status codes are:

  • 400 Bad Request — the request body or query parameters are invalid. For validation errors, the offending fields are listed under data.validationErrors.
  • 401 Unauthorized — the API key is missing or invalid (see Authorization).
  • 404 Not Found — the requested resource does not exist, or is not visible to your company.

Versioning ​

The version is part of every path. The current version is v2: it addresses everything by uuid, and new endpoints and webhooks exist there only. v1 keeps working and receives bug fixes, but no new features — Migrating to v2 lists every difference. Breaking changes get a new version; we announce them in the changelog. We detect who is using which version of the API, so you can continue using the old version until you are ready to upgrade.

Support ​

If you have any questions or need assistance, please refer to www.artesa.de or contact our support team.

Copyright © Artesa GmbH