Who can use this feature? Admins create the API key. Your developers use it to call the API.
Overview
The Atlas API lets another system do things in Atlas without anyone clicking in the app. Your website, your backend, your CRM or an internal tool can create customers, read conversations, send messages or list session recordings, all automatically.
Every request needs three things: your API key, the Atlas API address and the action you want. The Atlas developers portallists every action and lets you try them in your browser. The same requests work from any other app or server that can send web requests.
Atlas developers portal
See every endpoint, its fields and examples, and try requests right in your browser.
GET1https://api.atlas.so/v12/conversations3 Authorization: Bearer YOUR_API_KEY4 { "firstName": "John", "email": "john@example.com" }5← only for POST Atlas answers →200 OK + the data in JSON6
1 Method
The kind of action. GET reads data; POST creates or changes it.
2 Base URL
The address of the Atlas API. Every request starts with it.
3 Endpoint
The action you want, added to the base URL.
4 API key
A secret code that proves the request comes from your workspace.
5 Body
The data you send with a POST request, in JSON. GET requests don't need one.
6 Response
What Atlas sends back: 200 means it worked, 422 means a field is missing or wrong.
Think of it like a form your app fills in and sends to Atlas: the API key is the signature, the endpoint is the form's name and the body is what's written on it. Atlas answers with the result.
What you can do with the API
Click an area to see what it's for, an example and its main endpoints.
Conversations · List, create, update and read tickets, read their messages and send messages.
ExampleCreate a ticket when a customer fills in a form on your site.
GET /conversations · POST /conversations · POST /conversations/{id}/messages
Important: Treat your API key like a password. Use it only on your server or in trusted tools, never in your website's code, where anyone could see it.
Examples
Create or update a customer
Sends a customer's details to Atlas. If the customer exists, Atlas updates them; if not, Atlas creates them.
Sends a reply to the customer in an existing ticket. Replace CONVERSATION_ID with the ticket's ID and AGENT_ID with the ID of the agent who sends it.
curl --request POST \ --url 'https://api.atlas.so/v1/conversations/CONVERSATION_ID/messages' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "text": "Hi! Your order has shipped.", "agentId": "AGENT_ID" }'
The message appears in the ticket, like any agent reply.
FAQs & Troubleshooting
Can another app do the same things as the developers portal?
Yes. The portal is just a test console. Any app or server that can send web requests with your API key can make the same calls, for example your backend, an internal tool or an automation platform.
Do I need a developer?
To try a request in the developers portal, no. To use the API in your own app or tool, yes.
My request doesn't work. What should I check?
The API key is correct and is sent as Authorization: Bearer YOUR_API_KEY.
The URL starts with https://api.atlas.so/v1.
For POST requests, the body is valid JSON and includes the required fields. A 422 error means a field is missing or has the wrong format.
How do I find a ticket's ID or an agent's ID?
You can find a ticket's ID in two ways:
In Atlas, open the ticket and look at your browser's address bar. The ID is the code after conversationId=.
In Atlas, open the ticket's details and click the copy icon next to its ID.
List conversations also returns ticket IDs, and List users returns agent IDs.
