API Reference Overview

OpenPrime provides a RESTful API for managing infrastructure environments, credentials, and code generation.

Base URL

Development: http://localhost:3001/api
Production:  https://api.openprime.io/api

Authentication

All API endpoints require authentication via JWT Bearer token obtained from Keycloak.

Authorization: Bearer <access_token>

Obtaining Tokens

Tokens are obtained through the Keycloak OIDC flow. For programmatic access:

# Get token using client credentials
TOKEN=$(curl -s -X POST \
  "http://localhost:8080/realms/openprime/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=openprime-cli" \
  -d "client_secret=YOUR_SECRET" \
  -d "grant_type=client_credentials" \
  | jq -r '.access_token')

# Use token in API calls
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/environments

Request/Response Format

Content Type

Content-Type: application/json
Accept: application/json

Request Headers

Header	Description	Required
Authorization	Bearer token	Yes
Content-Type	application/json	Yes (for POST/PUT)
X-Request-ID	Correlation ID for tracing	No

Response Format

Success Response:

{
  "data": { ... },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable message",
    "details": [ ... ]
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request (validation error)
401	Unauthorized (missing/invalid token)
403	Forbidden (insufficient permissions)
404	Not Found
409	Conflict (duplicate resource)
422	Unprocessable Entity
429	Too Many Requests (rate limited)
500	Internal Server Error

Rate Limiting

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699999999

Default limits:

• 100 requests per 15-minute window per IP
• 1000 requests per hour per user

Pagination

List endpoints support pagination:

GET /api/environments?page=1&limit=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Filtering

Use query parameters for filtering:

GET /api/environments?provider=aws&status=active

Sorting

GET /api/environments?sort=created_at&order=desc

API Endpoints Summary

Environments

Method	Endpoint	Description
GET	/environments	List environments
POST	/environments	Create environment
GET	/environments/:id	Get environment
PUT	/environments/:id	Update environment
DELETE	/environments/:id	Delete environment
POST	/environments/:id/generate	Start a generation job
POST	/environments/:id/push	Push the generated repository to the customer's Git
POST	/environments/terraform-backend/create	Create the S3 state backend via StateCraft

There is no export endpoint

GET /environments/:id/export was listed here and has never existed. The wizard's "export configuration" is assembled client-side from the environment the API already returns.

Jobs

Generation and push are asynchronous. POST /environments/:id/generate returns a job; poll it, then download the artifact.

Method	Endpoint	Description
GET	/jobs/:jobId	Job status — queued, running, succeeded, failed
GET	/jobs/:jobId/download	Download the generated archive

Catalog

Method	Endpoint	Description
GET	/catalog	The service catalog extracted from the templates

Returns the document described in Service Catalog. The ETag is the templates commit, so a client holding the current catalog gets a 304. A Warning: 110 header means the catalog is being served from cache because Injecto was unreachable.

Cloud credentials

The path is /cloud-credentials

Earlier versions of this page documented /credentials. That path has never been mounted and returns 404.

Method	Endpoint	Description
GET	/cloud-credentials	List credentials
POST	/cloud-credentials	Create credential
GET	/cloud-credentials/:credentialId	Get credential
PUT	/cloud-credentials/:credentialId	Update credential
DELETE	/cloud-credentials/:credentialId	Delete credential
PUT	/cloud-credentials/:credentialId/default	Mark as the account default

Secret values are AES-256-GCM encrypted at rest and redacted from every response.

User

Method	Endpoint	Description
GET	/users/me	Get current user
PUT	/users/me	Update current user
GET	/users/me/preferences	Get preferences
PUT	/users/me/preferences	Update preferences
GET	/users	List all users — admin only

AI

Method	Endpoint	Description
POST	/ai/chat	Configuration assistance via AWS Bedrock

Health

Method	Endpoint	Description
GET	/health	Health check — served at the server root, not under /api

/health/ready does not exist

Only GET /health is served. It is mounted on the application root, so the URL is https://api.openprime.io/health, outside the /api prefix and outside the rate limiter.

SDK Examples

JavaScript/TypeScript

const response = await fetch('http://localhost:3001/api/environments', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const { data } = await response.json();

Python

import requests

response = requests.get(
    'http://localhost:3001/api/environments',
    headers={'Authorization': f'Bearer {token}'}
)

data = response.json()['data']

cURL

curl -X GET \
  "http://localhost:3001/api/environments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Versioning

The API is versioned via URL path (planned):

/api/v1/environments
/api/v2/environments

Currently, the API is unversioned (/api/environments). Breaking changes will be communicated before implementation.