API Getting Started

Reading time: 10 minutes

Integrate with Atlas programmatically using the REST API. This guide covers authentication, base URL, rate limits, request/response format, error handling, pagination, and webhooks.

---

Base URL

All API requests use the following base URL:

https://api.atlas-accounting.com/api/v1

The API follows REST conventions with JSON request and response bodies.

---

Authentication

Atlas uses JWT (JSON Web Token) authentication with refresh tokens.

Obtaining Tokens

POST /auth/login
Content-Type: application/json

{
  "email": "your@email.com",
  "password": "your-password"
}

Response:

{
  "tokens": {
    "access_token": "eyJhbG...",
    "refresh_token": "eyJhbG...",
    "token_type": "bearer",
    "expires_in": 3600
  },
  "user": {
    "id": "uuid",
    "email": "your@email.com",
    "full_name": "Your Name",
    "role": "admin"
  }
}

Using Tokens

Include the access token in the Authorization header:

Authorization: Bearer eyJhbG...

Refreshing Tokens

When the access token expires (after 1 hour):

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbG..."
}

---

Rate Limits

Tier	Requests per Minute	Burst
Standard	60	10
Professional	300	50
Enterprise	1000	100

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1680000000

When rate limited, the API returns 429 Too Many Requests.

---

Request Format

Content Type

All requests with a body must use:

Content-Type: application/json

Organization Context

Most endpoints require a company context. Include the company ID in the request path or as a query parameter where specified.

---

Response Format

Success Responses

{
  "id": "uuid",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  ...
}

List Responses

{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 50,
  "has_next": true
}

---

Error Handling

Error Response Format

{
  "detail": "Human-readable error message",
  "status_code": 422,
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be greater than zero"
    }
  ]
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request — invalid input
401	Unauthorized — invalid or expired token
403	Forbidden — insufficient permissions
404	Not Found
409	Conflict — duplicate or state conflict
422	Validation Error — check the errors array
429	Rate Limited — slow down
500	Internal Server Error

---

Pagination

List endpoints support cursor-based pagination:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	50	Items per page (max 100)
sort_by	string	varies	Sort field
sort_order	string	"desc"	"asc" or "desc"

Example

GET /api/v1/invoices?page=2&page_size=25&sort_by=created_at&sort_order=desc

---

First API Call

Let's fetch the current user's profile:

curl -X GET https://api.atlas-accounting.com/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": "uuid",
  "email": "your@email.com",
  "full_name": "Your Name",
  "role": "admin",
  "organization": {
    "id": "uuid",
    "name": "Your Organization"
  },
  "companies": [
    {
      "id": "uuid",
      "name": "Your Company",
      "role": "admin"
    }
  ]
}

---

Common Endpoints

Endpoint	Method	Description
/auth/me	GET	Current user profile
/companies	GET	List companies
/invoices	GET, POST	List and create invoices
/bills	GET, POST	List and create bills
/journal-entries	GET, POST	List and create journal entries
/contacts/customers	GET, POST	List and create customers
/contacts/vendors	GET, POST	List and create vendors
/reports/profit-loss	GET	Profit & Loss report
/reports/balance-sheet	GET	Balance Sheet report
/chart-of-accounts	GET	Chart of Accounts

---

Webhooks

Receive real-time notifications when events occur in Atlas.

Setting Up Webhooks

1. Go to Settings > API > Webhooks
2. Click New Webhook
3. Enter:
   • URL — your endpoint that receives webhook events
   • Events — select which events to subscribe to
   • Secret — used to verify webhook signatures

Available Events

Event	Triggered When
invoice.created	A new invoice is created
invoice.sent	An invoice is sent to a customer
invoice.paid	An invoice is fully paid
bill.approved	A bill is approved
payment.received	A payment is recorded
period.closed	An accounting period is closed

Webhook Payload

{
  "event": "invoice.paid",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "uuid",
    "invoice_number": "INV-001",
    "amount": 1500.0,
    "currency": "USD",
    "customer_id": "uuid"
  }
}

Verifying Signatures

Each webhook includes an X-Atlas-Signature header. Verify it by computing an HMAC-SHA256 of the payload using your webhook secret.

---

SDKs and Libraries

Official client libraries:

Language	Package
Python	pip install atlas-accounting
JavaScript/TypeScript	npm install @atlas-accounting/sdk

---

Related Guides

• RBAC & Permissions — API permissions match user roles
• Getting Started — setting up your account

What's Next

• Get your API tokens by logging in via the API
• Explore the endpoints with the API Reference (coming soon)
• Set up webhooks for real-time event notifications