Getting Started with the agentOS API

Getting an API key

The agentOS API operates on a self-service basis. To obtain an API key, contact your client and request that they generate and provide one. Documentation on how clients can create and manage API keys is available separately.

Important: API keys only grant access to the specific API tiers that the client has enabled for that key. If you receive a 401 error on a particular endpoint, the key may not have permission for that tier — ask your client to check.

Understanding the shortName parameter

Every API endpoint requires a {shortName} parameter in the URL. This is the unique identifier for the client organisation whose data you are accessing. Your client should provide this alongside your API key. If they haven't, contact them to retrieve it.

Example URL structure:

https://live-api.letmc.com/v4/{tier}/{shortName}/{endpoint}

Base URL

All API requests should be made to:

https://live-api.letmc.com

All requests must use HTTPS. HTTP is not supported.

Authentication

Include your API key as a request header:

api_key: your-api-key-here

Or as a query parameter:

?api_key=your-api-key-here

Testing your connection

Test your setup using the company endpoint on V4 Advertising:

GET https://live-api.letmc.com/v4/advertising/{shortName}/company/company
api_key: your-api-key-here

You can also explore and test all endpoints interactively using the agentOS Swagger UI at: https://live-api.letmc.com/swagger/ui/index

Pagination

Endpoints that return large datasets use offset and count pagination:

• count — total number of records to return (maximum 1,000)
• offset — index of the first record to return

For example, to retrieve items 10–20, use offset=10&count=10.

Rate limiting

API keys are limited to 50 requests per minute. The API is not designed for live, real-time data export. The recommended pattern is to run a scheduled job that imports data into your own storage layer, and then query that storage layer from your application. See the separate article on API throttle limits for full guidance.

Response format

All API responses are returned as JSON with UTF-8 encoding.

Authentication error responses

Need help?

Contact: api@agentos.com