REST API - Ralph

Ralph exposes many resources and operations through a RESTful web API that can be used for both querying the database and populating it with data. The API is built on Django REST Framework.

Authentication

Ralph uses token-based authentication for API access. Each user has an auto-generated personal token.

Obtaining Your Token

You can obtain your token either by visiting your profile page or by sending a request to the api-token-auth endpoint:

curl -H "Content-Type: application/json" \
  -X POST https://<YOUR-RALPH-URL>/api-token-auth/ \
  -d '{"username": "<YOUR-USERNAME>", "password": "<YOUR-PASSWORD>"}'

Response:

{"token":"79ee13720dbf474399dde532daad558aaeb131c3"}

If you don’t have an API token assigned, the above request will generate one automatically.

Using Your Token

Include your API token in the Authorization header for each request:

curl -X GET https://<YOUR-RALPH-URL>/api/ \
  -H 'Authorization: Token <YOUR-TOKEN>'

API Versioning

The API requires clients to specify the version in the Accept header:

GET /api/data-center-assets/ HTTP/1.1
Host: example.com
Accept: application/json; version=v1
Authorization: Token <YOUR-TOKEN>

Output Formats

Ralph API supports:

JSON (default) - For programmatic access
HTML preview - Browse to https://<YOUR-RALPH-URL>/api/ in your browser for an interactive preview

HTTP Methods

The following methods are available in the API:

Method	On a Collection	On a Single Resource
GET	Get full list of resources	Get resource details
POST	Add a new resource	-
PUT	-	Edit the resource (all data required)
PATCH	-	Edit the resource (only changed data required)
DELETE	-	Remove the resource

Getting Resources

Get a Single Resource

Use HTTP GET to retrieve details of a specific resource:

curl https://<YOUR-RALPH-URL>/api/data-center-assets/1/ \
  -H 'Authorization: Token <YOUR-TOKEN>' | python -m json.tool

Response:

{
    "id": 11105,
    "url": "http://127.0.0.1:8000/api/data-center-assets/1/",
    "hostname": "aws-proxy-1.my-dc",
    "status": "used",
    "sn": "12345",
    "barcode": "54321",
    "price": "55500.00",
    "remarks": "Used as proxy to AWS",
    "position": 12,
    "orientation": "front",
    "configuration_path": "/aws_proxy/prod",
    "service_env": {
        "id": 11,
        "url": "http://127.0.0.1:8000/api/service-environments/11/",
        "service": {
            "id": 1,
            "url": "http://127.0.0.1:8000/api/services/1/",
            "name": "AWS Proxy"
        },
        "environment": {
            "id": 2,
            "url": "http://127.0.0.1:8000/api/environments/2/",
            "name": "prod"
        }
    },
    "model": {
        "id": 168,
        "url": "http://127.0.0.1:8000/api/asset-models/168/",
        "name": "R630",
        "type": "data_center",
        "power_consumption": 1234,
        "height_of_device": 1.0,
        "cores_count": 8,
        "manufacturer": {
            "id": 33,
            "url": "http://127.0.0.1:8000/api/manufacturers/33/",
            "name": "Dell"
        }
    },
    "rack": {
        "id": 15,
        "url": "http://127.0.0.1:8000/api/racks/15/",
        "name": "Rack 123",
        "server_room": {
            "id": 1,
            "url": "http://127.0.0.1:8000/api/server-rooms/1/",
            "name": "Room 1",
            "data_center": {
                "id": 99,
                "url": "http://127.0.0.1:8000/api/data-centers/99/",
                "name": "New York"
            }
        }
    }
}

Get a List of Resources

curl https://<YOUR-RALPH-URL>/api/data-center-assets/ \
  -H 'Authorization: Token <YOUR-TOKEN>'

Saving Resources

Update a Resource (PATCH)

Use PATCH to update specific fields without providing all data:

curl -X PATCH https://<YOUR-RALPH-URL>/api/data-center-assets/1/ \
  -H 'Authorization: Token <YOUR-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "hostname": "aws-proxy-2.my-dc",
    "status": "damaged",
    "service_env": 12,
    "licences": [1, 2, 3]
  }'

Important points when saving resources:

To set a related object (foreign key), pass its ID (e.g., "service_env": 12)
To set many-to-many relations, pass an array of IDs (e.g., "licences": [1, 2, 3])
You can use text values for choice fields (e.g., "status": "damaged"), even if stored as numbers

Create a Resource (POST)

curl -X POST https://<YOUR-RALPH-URL>/api/data-center-assets/ \
  -H 'Authorization: Token <YOUR-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "hostname": "new-server.my-dc",
    "status": "new",
    "model": 168,
    "rack": 15,
    "position": 10,
    "service_env": 11
  }'

Filtering

Ralph API supports multiple query filters to help you find the exact resources you need.

Check Available Filters

Send an OPTIONS request to see which fields support filtering:

curl -X OPTIONS https://<YOUR-RALPH-URL>/api/data-center-assets/ \
  -H 'Authorization: Token <YOUR-TOKEN>'

Look for the filtering field in the response.

Filter Types

Exact Match Filter

Filter by exact field value:

curl "https://<YOUR-RALPH-URL>/api/data-center-assets/?hostname=s1234.local" \
  -H 'Authorization: Token <YOUR-TOKEN>'

Lookup Filters

Use Django’s __ convention for advanced lookups:

# Hostname starts with 's123'
curl "https://<YOUR-RALPH-URL>/api/data-center-assets/?hostname__startswith=s123" \
  -H 'Authorization: Token <YOUR-TOKEN>'

# Invoice date less than or equal to 2015-01-01
curl "https://<YOUR-RALPH-URL>/api/data-center-assets/?invoice_date__lte=2015-01-01" \
  -H 'Authorization: Token <YOUR-TOKEN>'

Common lookup operators:

__startswith - Starts with
__endswith - Ends with
__contains - Contains (case-sensitive)
__icontains - Contains (case-insensitive)
__lte - Less than or equal
__gte - Greater than or equal
__in - In a list of values

See Django Field lookups documentation for more operators.

Extended Filters

Extended filters work across multiple fields in polymorphic models like BaseObject:

# Search by name across multiple asset types
curl "https://<YOUR-RALPH-URL>/api/base-objects/?name=s1234.local" \
  -H 'Authorization: Token <YOUR-TOKEN>'

# Extended filters also support lookups
curl "https://<YOUR-RALPH-URL>/api/base-objects/?name__startswith=s123" \
  -H 'Authorization: Token <YOUR-TOKEN>'

Tag Filters

Filter by one or more tags. Multiple tags are combined with AND logic:

# Find all assets with both tag1 AND tag2
curl "https://<YOUR-RALPH-URL>/api/data-center-assets/?tag=tag1&tag=tag2" \
  -H 'Authorization: Token <YOUR-TOKEN>'

Transitions API

The Transitions API allows you to execute workflow transitions on assets.

List Available Transitions

Get all available transitions for a specific asset:

curl https://<YOUR-RALPH-URL>/api/data-center-assets/46/transitions/ \
  -H 'Authorization: Token <YOUR-TOKEN>'

Response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 5,
            "url": "<URL>/api/transitions/5/",
            "source": [
                "new",
                "in use",
                "free",
                "damaged",
                "liquidated",
                "to deploy"
            ],
            "target": "Keep original status",
            "name": "Change rack",
            "run_asynchronously": true,
            "async_service_name": "ASYNC_TRANSITIONS",
            "model": "<URL>/api/transitions-model/2/",
            "actions": [
                "<URL>/api/transitions-action/22/"
            ]
        }
    ]
}

Get Transition Parameters

Use OPTIONS to see what parameters a transition requires:

curl -X OPTIONS \
  "https://<YOUR-RALPH-URL>/api/virtual/virtualserver/767/transitions/Initialization/" \
  -H 'Authorization: Token <YOUR-TOKEN>'

Response:

{
  "name": "Transition",
  "description": "Transition API endpoint for selected model.",
  "actions": {
    "POST": {
      "network_environment": {
        "type": "choice",
        "required": true,
        "read_only": false,
        "label": "Network environment",
        "choices": [
          {
            "display_name": "aa0003bb (testowa)",
            "value": "1"
          },
          {
            "display_name": "Other",
            "value": "__other__"
          }
        ]
      }
    }
  }
}

Execute a Transition

Run a transition by POSTing to the transition endpoint:

curl -X POST \
  "https://<YOUR-RALPH-URL>/api/virtual/virtualserver/767/transitions/Initialization/" \
  -H 'Authorization: Token <YOUR-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "network_environment": "1"
  }'

Available Resources

Ralph exposes the following resource endpoints:

Assets & Inventory

/api/data-center-assets/ - Data center assets
/api/back-office-assets/ - Back office assets
/api/base-objects/ - All assets (polymorphic)
/api/asset-models/ - Hardware models
/api/manufacturers/ - Hardware manufacturers
/api/categories/ - Asset categories
/api/warehouses/ - Warehouses

Data Center Infrastructure

/api/racks/ - Server racks
/api/server-rooms/ - Server rooms
/api/data-centers/ - Data centers
/api/accessories/ - Rack accessories
/api/access-cards/ - Physical access cards
/api/access-zones/ - Access control zones

Services & Environments

/api/services/ - Business services
/api/service-environments/ - Service environments
/api/environments/ - Environments (prod, test, etc.)
/api/configuration-modules/ - Configuration modules
/api/configuration-classes/ - Configuration classes

Virtual & Cloud

/api/virtual-servers/ - Virtual machines
/api/cloud-hosts/ - Cloud instances
/api/clusters/ - Virtualization clusters

Networking

/api/networks/ - IP networks
/api/ip-addresses/ - IP addresses
/api/network-environments/ - Network environments

Licenses & Support

/api/licences/ - Software licenses
/api/software/ - Software catalog
/api/supports/ - Support contracts
/api/base-object-licences/ - Asset-license assignments

Telephony

/api/sim-cards/ - SIM cards

Security

/api/ssl-certificates/ - SSL/TLS certificates

Domains

/api/domains/ - Domain registrations
/api/domain-contracts/ - Domain contracts

User Management

/api/users/ - Users
/api/groups/ - Groups
/api/regions/ - Regional divisions
/api/teams/ - Support teams

Visit https://<YOUR-RALPH-URL>/api/ in your browser for an interactive list of all available endpoints and to explore the API.

Error Handling

The API uses standard HTTP status codes:

200 OK - Request succeeded
201 Created - Resource created successfully
204 No Content - Resource deleted successfully
400 Bad Request - Invalid request data
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User lacks permission for this resource
404 Not Found - Resource not found
500 Internal Server Error - Server error

Error responses include a JSON body with details:

{
  "detail": "Authentication credentials were not provided."
}

Rate Limiting

Ralph API does not impose rate limits by default, but administrators may configure rate limiting in their deployment. Contact your Ralph administrator for details.

Get Started

Installation

Core Features

User Guide

Integrations

Documentation Index

​Authentication

​Obtaining Your Token

​Using Your Token

​API Versioning

​Output Formats

​HTTP Methods

​Getting Resources

​Get a Single Resource

​Get a List of Resources

​Saving Resources

​Update a Resource (PATCH)

​Create a Resource (POST)

​Filtering

​Check Available Filters

​Filter Types

​Exact Match Filter

​Lookup Filters

​Extended Filters

​Tag Filters

​Transitions API

​List Available Transitions

​Get Transition Parameters

​Execute a Transition

​Available Resources

​Assets & Inventory

​Data Center Infrastructure

​Services & Environments

​Virtual & Cloud

​Networking

​Licenses & Support

​Telephony

​Security

​Domains

​User Management

​Error Handling

​Rate Limiting

Authentication

Obtaining Your Token

Using Your Token

API Versioning

Output Formats

HTTP Methods

Getting Resources

Get a Single Resource

Get a List of Resources

Saving Resources

Update a Resource (PATCH)

Create a Resource (POST)

Filtering

Check Available Filters

Filter Types

Exact Match Filter

Lookup Filters

Extended Filters

Tag Filters

Transitions API

List Available Transitions

Get Transition Parameters

Execute a Transition

Available Resources

Assets & Inventory

Data Center Infrastructure

Services & Environments

Virtual & Cloud

Networking

Licenses & Support

Telephony

Security

Domains

User Management

Error Handling

Rate Limiting