API Reference

The Goblins API allows you to programmatically manage your services, routes, configurations, and secrets. Use the API to automate deployments, integrate with CI/CD pipelines, or build custom tooling.

Base URL

All API requests should be made to your Goblins instance:

https://your-goblins-instance.com/api/

Authentication

All API requests require authentication. You can authenticate using:

• API Keys: Recommended for scripts, CI/CD, and automation
• Web Session: Used automatically when accessing the API from the web interface

See Authentication for details on creating and using API keys.

Quick Example

Here's how to list your services using an API key:

curl -H "Authorization: Bearer gob_your_api_key_here" \
  https://your-goblins-instance.com/api/services/

Available Endpoints

Resource	Endpoint	Description
Services	/api/services/	Deploy and manage containerized applications
Workers	/api/workers/	Manage background job processors
Routes	/api/routes/	Configure traffic routing
Domains	/api/domains/	Manage domain names
Configs	/api/configs/	Application configuration
Secrets	/api/secrets/	Encrypted secret storage
Deployments	/api/deployments/	Deployment history and rollbacks

Request Format

All requests that send data should use JSON:

curl -X POST https://your-goblins-instance.com/api/services/ \
  -H "Authorization: Bearer gob_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "image": "nginx:1.25",
    "port": 80
  }'

Response Format

Success Responses

Single Resource:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-service",
  "status": "ready",
  "created_at": "2024-10-15T12:00:00Z"
}

List of Resources:

{
  "count": 42,
  "next": "https://.../api/services/?page=2",
  "previous": null,
  "results": [
    { "id": "...", "name": "service-1" },
    { "id": "...", "name": "service-2" }
  ]
}

Error Responses

Validation Error (400):

{
  "name": ["This field is required"],
  "port": ["Ensure this value is between 1 and 65535"]
}

Authentication Error (401):

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

Permission Error (403):

{
  "detail": "You do not have permission to perform this action."
}

Not Found (404):

{
  "detail": "Not found."
}

Rate Limit Error (429):

{
  "detail": "Request was throttled. Expected available in 3600 seconds."
}

HTTP Status Codes

Code	Meaning	When Used
200	Success	GET, PATCH requests succeeded
201	Created	POST request created a new resource
204	No Content	DELETE request succeeded
400	Bad Request	Invalid data in request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	You don't have access to this resource
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Something went wrong on our end

Pagination

List endpoints return paginated results. Use the page query parameter:

# Get page 2
curl -H "Authorization: Bearer ..." \
  "https://.../api/services/?page=2"

The response includes pagination information:

• count: Total number of resources
• next: URL for the next page (null if last page)
• previous: URL for the previous page (null if first page)
• results: Array of resources for this page

Filtering by Project

All resources belong to a project. Filter by project using the project query parameter:

# List services in a specific project
curl -H "Authorization: Bearer ..." \
  "https://.../api/services/?project=123e4567-e89b-12d3-a456-426614174000"

Sorting

Many endpoints support sorting with the ordering parameter:

# Sort by name (ascending)
curl "https://.../api/services/?ordering=name"

# Sort by creation date (descending)
curl "https://.../api/services/?ordering=-created_at"

Rate Limits

To ensure fair usage, the API has rate limits:

Operation Type	Limit
Resource operations (create, update, delete)	100 requests/hour
Secret access	100 requests/hour

When you hit a rate limit, you'll receive a 429 Too Many Requests response. The Retry-After header indicates when you can retry.

Common Patterns

Creating a Resource

curl -X POST https://.../api/services/ \
  -H "Authorization: Bearer gob_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-service", "image": "nginx:1.25", "port": 80}'

Updating a Resource

curl -X PATCH https://.../api/services/{id}/ \
  -H "Authorization: Bearer gob_..." \
  -H "Content-Type: application/json" \
  -d '{"replicas_target": 3}'

Deleting a Resource

curl -X DELETE https://.../api/services/{id}/ \
  -H "Authorization: Bearer gob_..."

Next Steps

• Authentication - Learn how to authenticate
• Services - Deploy your applications
• Routes - Configure traffic routing