Skip to content

API overview

Pro

The Tapp API gives your own systems direct access to your Tapp data. This page covers what an API key can reach, creating a key, authenticating a request, rotating and revoking keys, rate limits and errors.

Pro tier
API access is only available on the Pro tier and above, get in touch with sales about getting access to this feature.

Available endpoints

The Tapp API provides several endpoints to retrieve or update your data.

Available endpoints

The full reference for these endpoints, with parameters, response fields and examples can be found in the endpoints section.

Creating a key

In the Dashboard, go to SettingsAPI keys and click New API key.

API key settings

Name
required
Only used for your own reference.
Permissions
required
Which actions the key may perform, per resource. Grant only what the integration needs.
Expiry date
The moment the key stops working. Leave it empty for a key that never expires.

A key is the text tapp_ followed by 32 hexadecimal characters. The Dashboard keeps the first 12 characters so you can tell keys apart, and stores the rest as a hash.

Example key
tapp_1f4c9a02d7b3e5618a0c4d2f9b7e3a15
The key is shown once
After creating your API key it is shown only once, so store it safely for later reference.

Authenticating a request

Send the key in the x-api-key header on every request.

Headers

x-api-keystring
required
The full key, including the tapp_ prefix.

Request

curl "https://api.tapp.online/v2/labelReports?pageSize=50" \
  --header "x-api-key: $TAPP_API_KEY"

const response = await fetch('https://api.tapp.online/v2/labelReports?pageSize=50', {
    headers: {
        'x-api-key': process.env.TAPP_API_KEY as string
    }
})

const { data, totalDocuments } = await response.json()

import os

import requests

response = requests.get(
    'https://api.tapp.online/v2/labelReports',
    params={'pageSize': 50},
    headers={'x-api-key': os.environ['TAPP_API_KEY']}
)

response.raise_for_status()
print(response.json()['totalDocuments'])

<?php

$context = stream_context_create([
    'http' => [
        'header' => 'x-api-key: ' . getenv('TAPP_API_KEY'),
    ],
]);

$body = file_get_contents(
    'https://api.tapp.online/v2/labelReports?pageSize=50',
    false,
    $context
);

$page = json_decode($body, true);

Rotating and revoking

Rotate
Generates a new key and invalidates the old one immediately. Use this when a key may have leaked, or on a schedule.
Expire
Set an expiry date so the key stops working on its own. Past that moment requests fail with 401.
Revoke
Deletes the key. Requests using it fail with 401 from that moment.

Rate limits

The API allows 20 requests per 10 seconds. Go over that and the next requests are blocked for 10 seconds returning a 429 error. Once those 10 seconds pass, requests are let through again.

The limit is counted per IP address, not per key. For bulk reads, ask for larger pages rather than more requests.

No rate limit headers
Responses do not say how much of the budget is left.

Errors

A failed request answers with the meaning in the HTTP status code and a short message in the body. The body is plain text, sent as text/plain; charset=utf-8, so parsing it as JSON fails. Branch on the status code and treat the message as something to log, not something to match on. A 429 is the exception: it is answered before the request reaches the API, so do not expect a body in that shape.

What the API answers

  • 400
    Names the field that failedThe query string or body did not match what the route expects.
  • 401
    Invalid API keyThe header is missing or malformed, or the key is unknown.
  • 401
    API key is disabledThe key exists but has been switched off.
  • 401
    API key has expiredThe key is past its expiry date.
  • 403
    This endpoint is not available for API keysThe route is valid but closed to API keys.
  • 403
    API key does not have 'update' permission on 'labelReports'The key is missing the permission the route needs.
  • 404
    label report not foundNo report with that id is visible to your company.
  • 429
    VariesMore than 20 requests in 10 seconds from the same IP address. Blocked for the next 10 seconds.
  • 500
    VariesThe request failed on our side.

API vs. Webhooks

Use our API to pull data on demand for scheduled tasks or reporting. For event-driven architectures, use webhooks to have label report data automatically pushed to your endpoint the moment a label is activated or tapped.