Services & APIs
REST API Reference
General API conventions, base URLs, pagination standards, and error payloads for 1st Services.
REST API Overview
The 1st Services API is organized around RESTful principles. All request bodies and responses use standard JSON encoding.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.1st-services.com/v1 |
| Sandbox / Mock | https://sandbox-api.1st-services.com/v1 |
Standard Response Envelope
Successful API requests return an HTTP 2xx status code wrapped in a consistent response envelope:
{
"status": "success",
"data": { ... },
"meta": {
"request_id": "req_839120489",
"timestamp": 1771849200
}
}
Pagination
List endpoints support cursor-based pagination with limit and starting_after query parameters:
GET /v1/shortener/links?limit=25&starting_after=link_884920 HTTP/1.1
{
"status": "success",
"data": [ ... ],
"meta": {
"has_more": true,
"next_cursor": "link_992144",
"total_count": 348
}
}
Error Handling & Error Codes
When an error occurs, the API returns an appropriate HTTP status code (4xx or 5xx) and a structured error object:
{
"status": "error",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested VPS instance ID 'vps_999' was not found.",
"field": "instance_id",
"doc_url": "https://docs.1st-services.com/services-api/api-reference#errors"
}
}
Common HTTP Status Codes
| Code | Status | Meaning |
|---|---|---|
200 | OK | Request succeeded. |
201 | Created | Resource provisioned successfully. |
400 | Bad Request | Malformed payload or validation error. |
401 | Unauthorized | Missing or invalid API key. |
403 | Forbidden | Key does not possess the required scopes. |
404 | Not Found | Target resource does not exist. |
409 | Conflict | Conflict (e.g. custom domain or slug already taken). |
429 | Too Many Requests | Rate limit exceeded. |
500 | Internal Server Error | Transient server error. Contact support. |