Authentication

The RAMSdoc API uses bearer token authentication. All API requests must include a valid token in the Authorization header.

Getting an API token

Log in to RAMSdoc and go to Settings > API.
Click Create API Token.
Enter a name for the token (e.g. “CI/CD Integration” or “Reporting Dashboard”).
Select the scopes — which API actions this token can perform (see scopes below).
Click Create.
Copy the token immediately — it is only shown once. Store it securely.

[Screenshot: API token creation dialog with name and scope selection]

Using the token

Include the token in the Authorization header of every request:

cURL

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json" \
     https://api.ramsdoc.com/api/v1/documents

JavaScript (fetch)

const response = await fetch('https://api.ramsdoc.com/api/v1/documents', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json',
  },
});
const data = await response.json();

Python (requests)

import requests

response = requests.get(
    'https://api.ramsdoc.com/api/v1/documents',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json',
    }
)
data = response.json()

Scopes

When creating a token, select which actions it can perform:

Scope	Permissions
`documents:read`	List and view documents
`documents:write`	Create, update, and delete documents
`projects:read`	List and view projects and sites
`projects:write`	Create and update projects and sites
`ai:use`	Trigger AI features (uses your organisation’s credits)
`users:read`	List and view organisation users
`webhooks:manage`	Configure webhook endpoints

Use the minimum scopes required for your integration. A reporting dashboard only needs documents:read and projects:read. A CI/CD pipeline generating RAMS might need documents:write and ai:use.

Base URL

All API requests use the base URL:

https://api.ramsdoc.com/api/v1/

Request format

Content-Type: application/json for request bodies
Accept: application/json for all requests
All request bodies must be valid JSON
All responses are JSON

Response format

Successful responses follow this structure:

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 142
  }
}

Single resources return data as an object. Collections return data as an array with pagination in meta.

Error responses

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": {
    "code": "validation_error",
    "message": "The title field is required.",
    "details": {
      "title": ["The title field is required."]
    }
  }
}

Status code	Meaning
`400`	Bad request — invalid parameters or request body
`401`	Unauthorised — missing or invalid token
`403`	Forbidden — token does not have the required scope
`404`	Not found — resource does not exist
`422`	Validation error — request body failed validation
`429`	Rate limited — too many requests (see rate limits)
`500`	Server error — something went wrong on our end

Rate limits

API requests are rate limited per token:

Plan	Requests per minute
Pro	60
Team	120
Enterprise	Custom

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1711382400

If you exceed the limit, you will receive a 429 response. Wait until the X-RateLimit-Reset timestamp before retrying.

Pagination

Collection endpoints return paginated results. Use query parameters to control pagination:

Parameter	Default	Description
`page`	1	Page number
`per_page`	25	Items per page (max 100)

Example:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.ramsdoc.com/api/v1/documents?page=2&per_page=50"

The meta object in the response includes current_page, per_page, total, last_page, and navigation links.

Revoking tokens

To revoke a token:

Go to Settings > API.
Find the token in the list.
Click Revoke.

The token is immediately invalidated. Any requests using it will receive a 401 response.