Vemetric REST API

Here you can find all the information you need to get started with our API.

The Vemetric API lets you read project data and integrate Vemetric into your own tooling.

Base URL

The API is available at https://api.vemetric.com

We also have an OpenAPI Spec (openapi.json) for easy integration with API clients and documentation tools.

Authentication

Authenticate using your private API key as a bearer token:

Authorization: Bearer <YOUR_API_KEY>

Keep your API key private

Never expose private API keys in frontend code. Use your backend or serverless functions for API calls.

Project and organization API keys

There are two kinds of API keys:

• Project API keys grant access to a single project. Create them in the settings of your project, on the API tab.
• Organization API keys grant access to several projects of an organization: either to all current and future projects, or only to the projects you choose when creating the key (projects created later aren’t added automatically). Create them in the organization settings, on the API tab.

Only organization admins can create and revoke API keys.

If you only need data from one project, a project API key is all you need. Use an organization API key if one integration reads data from several projects, for example a BI sync or an internal dashboard.

Manage API Keys

To manage project API keys, visit the settings page of your project and navigate to the API tab. There you can create new keys and revoke existing ones. Organization API keys are managed the same way on the API tab of the organization settings.

Once you’ve created the API Key, make sure to copy it and store it securely. You won’t be able to see the full key again after you leave the page.

Treat your API keys like passwords. Store each key in your secrets manager or environment variables, never in source code. Avoid sending keys in URLs or logs; always use the Authorization header.

If a key gets compromised:

1. Revoke the affected key in the project or organization settings.
2. Create a replacement key.
3. Update all dependent services and redeploy.
4. Monitor for new 401 errors from services that still use the old key.

Choosing the Project

Every endpoint returns data of one project. Which project that is depends on the kind of API key:

• Project API keys always use their own project. You don’t need to send anything else.
• Organization API keys need the ID of the project in the X-Vemetric-Project header of every request:

Authorization: Bearer <YOUR_API_KEY>
X-Vemetric-Project: <PROJECT_ID>

To find the project IDs, call GET /v1/projects. It returns all projects the API key has access to and doesn’t need the header:

curl https://api.vemetric.com/v1/projects \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "projects": [
    { "id": "1234567890123456", "name": "My Website", "domain": "example.com" }
  ]
}

Organization API keys always need the header, even if the key only has access to a single project. That way your integration keeps working when more projects are created later. A request without the header returns 400 with the error code PROJECT_REQUIRED. If the key has no access to the project in the header, or the project doesn’t exist, the API returns 404 with the error code PROJECT_NOT_FOUND.

{
  "error": {
    "code": "PROJECT_REQUIRED",
    "message": "Organization API keys need the project ID in the X-Vemetric-Project header. GET /v1/projects lists the projects this key covers."
  }
}

Project API keys can send the header too, but it has to be the ID of their own project.

Rate Limiting

The API is rate limited to protect service availability and ensure fair usage across projects. You’re allowed to send 100 requests per minute per project. All API keys that access a project share its limit. Requests of an organization API key that don’t name a project (GET /v1/projects) count against a separate limit of the key.

If you exceed the limit, the API responds with 429 Too Many Requests and a RATE_LIMIT_EXCEEDED error code.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}

When this happens, use exponential backoff (and jitter) in your client and avoid immediate retry loops. For high-volume integrations, batch requests where possible and cache responses when appropriate.

Endpoints

Here you can see all the available endpoints, categorized by their functionality. Click on each endpoint to see more details about the request and response format, as well as example requests.

All endpoints except GET /v1/projects operate on one project: the project of a project API key, or the project in the X-Vemetric-Project header for organization API keys (see Choosing the Project).