Integrate Cosmo AI from your server.

Authentication

Authenticate every production request with a key issued to the licensed workspace. If domain restrictions are enabled, identify the authorised integration hostname as well.

Authorization: Bearer cosmo_live_...
Content-Type: application/json
Idempotency-Key: your_unique_request_id
X-Cosmo-Domain: yourdomain.com

Create a prediction

POST /api/cosmo/v1/predict

{
  "birth": {
    "date": "YYYY-MM-DD",
    "time": "HH:MM",
    "latitude": 0.0000,
    "longitude": 0.0000,
    "timezone": "Area/City"
  },
  "analysisScope": ["career", "finance", "timing"]
}

The values above are format placeholders only. Completed predictions consume one licensed unit. Failed predictions release the quota reservation. Responses include a request identifier for support and integration tracing.

Analysis scopes

Request only the areas your product needs. Available licensed scopes can include core, career, finance, relationships, children, education, property, health, travel and timing. The licence determines which scopes are permitted.

Licence status

GET /api/cosmo/v1/status
Authorization: Bearer cosmo_live_...

Status requests do not consume prediction quota. Use this endpoint for integration diagnostics rather than exposing licence credentials to end users.

Retry safely

Use one stable Idempotency-Key for each logical prediction. If a network timeout causes a retry, the same completed request can be replayed without consuming another prediction unit. Reusing the same key with different input is rejected.

Versioning

The /v1 path is the compatibility boundary for this API generation. Materially breaking contract changes should be introduced under a new major API path rather than silently changing an existing integration.

Common errors

Data handling

Send only information required for the requested calculation. Do not include customer passwords, payment credentials, API secrets or unrelated personal information in prediction requests.