API Reference

Welcome to the AstroAPI Reference documentation. This section provides detailed information about all available endpoints.

OpenAPI Specification

The complete API is documented using the OpenAPI 3.1 specification. Use the sidebar to browse available endpoints organized by category.

Base URL

https://api.astroapi.cloud

Authentication

All API requests require authentication via:

• API Key: X-Api-Key header

See the Authentication Guide for details.

Response Format

All responses follow the JSON:API specification:

{
  "data": {
    "type": "resource-type",
    "id": "resource-id",
    "attributes": { ... }
  }
}

Error Responses

Errors follow JSON:API error format:

{
  "errors": [{
    "status": "400",
    "title": "Bad Request",
    "detail": "Detailed error message"
  }]
}

Common HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions or module access
404	Not Found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

v1.0.0

AstroAPI

Download OpenAPI Document

JSON

Download OpenAPI Document

YAML

Professional astrology API for natal charts, transits, synastry, and interpretations

Servers

https://api.astroapi.cloudProduction

---

Content

Content management and interpretation texts

Operations

POST/api/content/{id}/create-custom-copyPOST/api/content/{id}/restoreDELETE/api/content/{id}GET/api/content/{horoscopeType}/{contentType}POST/api/content/{horoscopeType}/{contentType}GET/api/content/{horoscopeType}/{contentType}/{id}DELETE/api/content/{horoscopeType}/{contentType}/{id}

---

Create Custom Copy

POST

/api/content/{id}/create-custom-copy

Create an organization-specific copy of system content for customization.

Parameters

Path Parameters

id*

Typestring

Required

Responses

Create a custom copy of system content

Content-Type

application/vnd.api+json

{

"data": {

"type": "content",

"id": "string",

"attributes": {

"urn": "string",

"title": "string",

"body": "string",

"metadata": null,

"owner_type": "string",

"owner_id": "string",

"base_content_id": "string",

"created_at": "string",

"updated_at": "string"

},

"links": {

"self": "string"

}

}

}

POST

/api/content/{id}/create-custom-copy

Playground

Variables

Key

Value

id*

Samples

---

Restore Content

POST

/api/content/{id}/restore

Restore custom content to match the original system content.

Parameters

Path Parameters

id*

Typestring

Required

Responses

Restore custom content to match system content

Content-Type

application/vnd.api+json

{

"data": {

"type": "content",

"id": "string",

"attributes": {

"urn": "string",

"title": "string",

"body": "string",

"metadata": null,

"owner_type": "string",

"owner_id": "string",

"base_content_id": "string",

"created_at": "string",

"updated_at": "string"

},

"links": {

"self": "string"

}

}

}

POST

/api/content/{id}/restore

Playground

Variables

Key

Value

id*

Samples

---

Delete Content by ID

DELETE

/api/content/{id}

Delete a content item by its ID.

Parameters

Path Parameters

id*

Typestring

Required

Responses

Delete one content item

Content-Type

application/vnd.api+json

{

"data": {

"type": "content",

"id": "string",

"attributes": {

"urn": "string",

"title": "string",

"body": "string",

"metadata": null,

"owner_type": "string",

"owner_id": "string",

"base_content_id": "string",

"created_at": "string",

"updated_at": "string"

},

"links": {

"self": "string"

}

}

}

DELETE

/api/content/{id}

Playground

Variables

Key

Value

id*

Samples

---

List Content

GET

/api/content/{horoscopeType}/{contentType}

Retrieve a paginated list of content items filtered by horoscope and content type.

Parameters

Path Parameters

horoscopeType*

Typestring

Required

contentType*

Typestring

Required

Responses

Retrieve content items

Content-Type

application/vnd.api+json

{

"data": {

"type": "content",

"id": "string",

"attributes": {

"urn": "string",

"title": "string",

"body": "string",

"metadata": null,

"owner_type": "string",

"owner_id": "string",

"base_content_id": "string",

"created_at": "string",

"updated_at": "string"

},

"links": {

"self": "string"

}

}

}

GET

/api/content/{horoscopeType}/{contentType}

Playground

Variables

Key

Value

horoscopeType*

contentType*

Samples

---

Create Content

POST

/api/content/{horoscopeType}/{contentType}

Create a new content item for a specific horoscope and content type.

Parameters

Path Parameters

horoscopeType*

Typestring

Required

contentType*

Typestring

Required

Responses

Create content item

Content-Type

application/vnd.api+json

{

"data": {

"type": "content",

"id": "string",

"attributes": {

"urn": "string",

"title": "string",

"body": "string",

"metadata": null,

"owner_type": "string",

"owner_id": "string",

"base_content_id": "string",

"created_at": "string",

"updated_at": "string"

},

"links": {

"self": "string"

}

}

}

POST

/api/content/{horoscopeType}/{contentType}

Playground

Variables

Key

Value

horoscopeType*

contentType*

Samples

---

Get Content

GET

/api/content/{horoscopeType}/{contentType}/{id}

Retrieve a single content item by its ID.

Parameters

Path Parameters

id*

Typestring

Required

horoscopeType*

Typestring

Required

contentType*

Typestring

Required

Responses

Retrieve one content item

Content-Type

application/vnd.api+json

{

"data": {

"type": "content",

"id": "string",

"attributes": {

"urn": "string",

"title": "string",

"body": "string",

"metadata": null,

"owner_type": "string",

"owner_id": "string",

"base_content_id": "string",

"created_at": "string",

"updated_at": "string"

},

"links": {

"self": "string"

}

}

}

GET

/api/content/{horoscopeType}/{contentType}/{id}

Playground

Variables

Key

Value

id*

horoscopeType*

contentType*

Samples

---

Delete Content

DELETE

/api/content/{horoscopeType}/{contentType}/{id}

Delete a content item by horoscope type, content type, and ID.

Parameters

Path Parameters

id*

Typestring

Required

horoscopeType*

Typestring

Required

contentType*

Typestring

Required

Responses

Delete one content item

DELETE

/api/content/{horoscopeType}/{contentType}/{id}

Playground

Variables

Key

Value

id*

horoscopeType*

contentType*

Samples

---

Calculations

Astrological calculations including natal charts, transits, synastry, and more

Operations

POST/api/calc/natalPOST/api/calc/synastryPOST/api/calc/compositePOST/api/calc/transitPOST/api/calc/compatibilityPOST/api/calc/solar-returnPOST/api/calc/lunar-returnPOST/api/calc/chinese-horoscopePOST/api/calc/chinese-forecast

---

Natal Chart

POST

/api/calc/natal

Calculate a natal (birth) chart with planetary positions, house cusps, and aspects.

Request Body

application/json

{

"dateTime": "string",

"location": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"houseSystem": "placidus",

"language": "en",

"includeText": true,

"includeReadableEntities": false,

"points": [

"string"

],

"orbs": {

"additionalProperties": 0

}

}

Responses

Calculate natal chart

Content-Type

application/vnd.api+json

{

"data": {

"dateTime": "string",

"aspects": [

{

"pointA": "string",

"pointB": "string",

"aspect": "string",

"angle": 0,

"orb": 0,

"applying": true,

"text": "string"

}

],

"points": {

"additionalProperties": {

}

},

"houses": {

"cusps": [

0

],

"ascmc": [

0

]

},

"chart": {

"url": "string"

}

}

}

POST

/api/calc/natal

Playground

Body

Samples

---

Synastry Chart

POST

/api/calc/synastry

Calculate synastry aspects between two birth charts for relationship analysis.

Request Body

application/json

{

"dateTime1": "string",

"location1": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"dateTime2": "string",

"location2": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"houseSystem": "placidus",

"language": "en",

"includeText": true,

"includeReadableEntities": false,

"points": [

"string"

],

"orbs": {

"additionalProperties": 0

}

}

Responses

Calculate synastry chart

Content-Type

application/vnd.api+json

{

"data": {

"aspects1to2": [

{

"pointA": "string",

"pointB": "string",

"aspect": "string",

"angle": 0,

"orb": 0,

"applying": true,

"text": "string"

}

],

"aspects2to1": [

{

"pointA": "string",

"pointB": "string",

"aspect": "string",

"angle": 0,

"orb": 0,

"applying": true,

"text": "string"

}

]

}

}

POST

/api/calc/synastry

Playground

Body

Samples

---

Composite Chart

POST

/api/calc/composite

Calculate a composite chart by combining midpoints of two birth charts.

Request Body

application/json

{

"dateTime1": "string",

"location1": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"dateTime2": "string",

"location2": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"houseSystem": "placidus",

"language": "en",

"includeText": true,

"includeReadableEntities": false,

"points": [

"string"

],

"orbs": {

"additionalProperties": 0

}

}

Responses

Calculate composite chart

Content-Type

application/vnd.api+json

{

"data": {

"points": {

"additionalProperties": {

}

},

"aspects": [

{

"pointA": "string",

"pointB": "string",

"aspect": "string",

"angle": 0,

"orb": 0,

"applying": true,

"text": "string"

}

]

}

}

POST

/api/calc/composite

Playground

Body

Samples

---

Transit Chart

POST

/api/calc/transit

Calculate planetary transits over a natal chart for a specified time period.

Request Body

application/json

{

"birthDate": "string",

"birthLocation": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"transitDateStart": "string",

"transitDateEnd": "string",

"transitLocation": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"houseSystem": "placidus",

"language": "en",

"includeText": true,

"includeReadableEntities": false,

"points": [

"string"

]

}

Responses

Calculate transits chart

Content-Type

application/vnd.api+json

{

"data": {

"crossings": {

"additionalProperties": [

]

},

"aspects": [

]

}

}

POST

/api/calc/transit

Playground

Body

Samples

---

Compatibility Analysis

POST

/api/calc/compatibility

Calculate sun sign compatibility between two people with interpretation text.

Request Body

application/json

{

"dateTime1": "string",

"location1": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"dateTime2": "string",

"location2": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"language": "en",

"includeText": true,

"includeReadableEntities": false

}

Responses

Calculate compatibility between two birth charts

Content-Type

application/vnd.api+json

{

"data": {

"sign1": "string",

"sign2": "string",

"text": "string"

}

}

POST

/api/calc/compatibility

Playground

Body

Samples

---

Solar Return

POST

/api/calc/solar-return

Calculate the solar return chart for a specific year (birthday chart).

Request Body

application/json

{

"birthDateTime": "string",

"birthLocation": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"returnYear": 0,

"houseSystem": "placidus",

"language": "en",

"includeText": true,

"includeReadableEntities": false,

"points": [

"string"

],

"orbs": {

"additionalProperties": 0

}

}

Responses

Calculate solar return chart

Content-Type

application/vnd.api+json

{

"data": {

"returnYear": 0,

"returnDate": "string",

"aspects": [

{

"pointA": "string",

"pointB": "string",

"aspect": "string",

"angle": 0,

"orb": 0,

"applying": true,

"text": "string"

}

],

"points": {

"additionalProperties": {

}

},

"houses": {

"cusps": [

0

],

"ascmc": [

0

]

},

"chart": {

"url": "string"

}

}

}

POST

/api/calc/solar-return

Playground

Body

Samples

---

Lunar Return

POST

/api/calc/lunar-return

Calculate the lunar return chart when the Moon returns to its natal position.

Request Body

application/json

{

"birthDateTime": "string",

"birthLocation": {

"longitude": 0,

"latitude": 0,

"timezone": "string"

},

"returnDate": "string",

"houseSystem": "placidus",

"language": "en",

"includeText": true,

"includeReadableEntities": false,

"points": [

"string"

],

"orbs": {

"additionalProperties": 0

}

}

Responses

Calculate lunar return chart

Content-Type

application/vnd.api+json

{

"data": {

"returnDate": "string",

"aspects": [

{

"pointA": "string",

"pointB": "string",

"aspect": "string",

"angle": 0,

"orb": 0,

"applying": true,

"text": "string"

}

],

"points": {

"additionalProperties": {

}

},

"houses": {

"cusps": [

0

],

"ascmc": [

0

]

},

"chart": {

"url": "string"

}

}

}

POST

/api/calc/lunar-return

Playground

Body

Samples

---

Chinese Zodiac Sign

POST

/api/calc/chinese-horoscope

Calculate the Chinese zodiac sign and element based on birth year.

Request Body

application/json

{

"birthDate": "string",

"language": "en",

"includeText": true,

"includeReadableEntities": false

}

Responses

Calculate Chinese horoscope sign

Content-Type

application/vnd.api+json

{

"data": {

"sign": "string",

"element": "string",

"year": 0,

"text": "string"

}

}

POST

/api/calc/chinese-horoscope

Playground

Body

Samples

---

Chinese Zodiac Forecast

POST

/api/calc/chinese-forecast

Get Chinese zodiac forecast for a specific year with category breakdowns.

Request Body

application/json

{

"birthDate": "string",

"forecastYear": 0,

"language": "en",

"includeText": true,

"includeReadableEntities": false

}

Responses

Calculate Chinese horoscope forecast

Content-Type

application/vnd.api+json

{

"data": {

"sign": "string",

"year": 0,

"text": "string",

"categories": {

"additionalProperties": "string"

}

}

}

POST

/api/calc/chinese-forecast

Playground

Body

Samples

---

Organizations

Organization and team management

Operations

POST/api/orgGET/api/org/usersPOST/api/org/usersDELETE/api/org/users/{memberId}PATCH/api/org/users/{memberId}

---

Create Organization

POST

/api/org

Create a new organization with Stripe billing setup.

Responses

Create organization

Content-Type

application/vnd.api+json

[

]

POST

/api/org

Playground

Samples

---

List Members

GET

/api/org/users

Get a paginated list of organization members.

Responses

List organization users

Content-Type

application/vnd.api+json

{

"links": {

"self": "string",

"next": "string"

},

"data": [

{

"id": "string",

"type": "user",

"attributes": {

"email": "string",

"name": "string",

"role": "string"

}

}

],

"meta": {

"count": 0

}

}

GET

/api/org/users

Playground

Samples

---

Add Member

POST

/api/org/users

Add or invite a new member to the organization.

Request Body

application/json

{

"email": "string",

"name": "string",

"role": "string"

}

Responses

Member toegevoegd/uitgenodigd

Content-Type

application/vnd.api+json

{

"data": {

"memberId": "string",

"userId": "string",

"role": "string"

}

}

POST

/api/org/users

Playground

Body

Samples

---

Remove Member

DELETE

/api/org/users/{memberId}

Remove a member from the organization.

Parameters

Path Parameters

memberId*

Typestring

Required

Min Length1

Responses

Member verwijderd

DELETE

/api/org/users/{memberId}

Playground

Variables

Key

Value

memberId*

Samples

---

Update Member

PATCH

/api/org/users/{memberId}

Update an organization member's role.

Parameters

Path Parameters

memberId*

Typestring

Required

Min Length1

Request Body

application/json

{

"role": "string"

}

Responses

Member geüpdatet

Content-Type

application/vnd.api+json

{

"data": {

"memberId": "string",

"role": "string"

}

}

PATCH

/api/org/users/{memberId}

Playground

Variables

Key

Value

memberId*

Body

Samples

---

Modules

Module access and subscription management

Operations

GET/api/modulesGET/api/modules/organizationGET/api/modules/plansGET/api/modules/check/{moduleId}

---

List Modules

GET

/api/modules

Get all available modules with pricing information.

Responses

List all available modules

Content-Type

application/json

{

"data": [

{

"id": "string",

"name": "string",

"description": "string",

"category": "string",

"horoscopeType": "string",

"contentType": "string",

"priceCents": 0

}

]

}

GET

/api/modules

Playground

Samples

---

Organization Modules

GET

/api/modules/organization

Get the list of modules the current organization has access to.

Responses

List modules for current organization

Content-Type

application/json

{

"data": [

"string"

]

}

GET

/api/modules/organization

Playground

Samples

---

Subscription Plans

GET

/api/modules/plans

Get all available subscription plans with included modules and pricing.

Responses

List all subscription plans

Content-Type

application/json

{

"data": [

{

"id": "string",

"name": "string",

"description": "string",

"modules": [

"string"

],

"discountPercentage": 0,

"priceCents": 0,

"stripePriceId": "string"

}

]

}

GET

/api/modules/plans

Playground

Samples

---

Check Module Access

GET

/api/modules/check/{moduleId}

Check if the current organization has access to a specific module.

Parameters

Path Parameters

moduleId*

Typestring

Required

Responses

Check module access

Content-Type

application/json

{

"hasAccess": true

}

GET

/api/modules/check/{moduleId}

Playground

Variables

Key

Value

moduleId*

Samples

---

API Keys

API key management

Operations

GET/api/api-keysPOST/api/api-keysGET/api/api-keys/available-optionsGET/api/api-keys/{id}DELETE/api/api-keys/{id}PATCH/api/api-keys/{id}

---

List API Keys

GET

/api/api-keys

Get all API keys owned by the current user.

Responses

List of API keys

Content-Type

application/json

{

"data": [

{

"id": "string",

"name": "string",

"prefix": "string",

"start": "string",

"organizationId": "string",

"enabled": true,

"permissions": [

"string"

],

"modules": [

"string"

],

"expiresAt": "string",

"createdAt": "string",

"updatedAt": "string"

}

]

}

GET

/api/api-keys

Playground

Samples

---

Create API Key

POST

/api/api-keys

Create a new API key with optional permission and module restrictions.

Request Body

application/json

{

"name": "string",

"organizationId": "string",

"permissions": [

"string"

],

"modules": [

"string"

],

"expiresIn": 0

}

Responses

API key created

Content-Type

application/json

{

"data": {

"id": "string",

"key": "string",

"name": "string",

"prefix": "string",

"organizationId": "string",

"permissions": [

"string"

],

"modules": [

"string"

],

"expiresAt": "string"

}

}

POST

/api/api-keys

Playground

Body

Samples

---

Available Options

GET

/api/api-keys/available-options

Get available permissions and modules for configuring API keys.

Responses

Available options

Content-Type

application/json

{

"permissions": [

{

"id": "string",

"description": "string"

}

],

"modules": [

{

"id": "string",

"name": "string"

}

],

"userRole": "string",

"rolePermissions": [

"string"

]

}

GET

/api/api-keys/available-options

Playground

Samples

---

Get API Key

GET

/api/api-keys/{id}

Get details of a specific API key.

Parameters

Path Parameters

id*

Typestring

Required

Responses

API key details

Content-Type

application/json

{

"data": {

"id": "string",

"name": "string",

"prefix": "string",

"start": "string",

"organizationId": "string",

"enabled": true,

"permissions": [

"string"

],

"modules": [

"string"

],

"expiresAt": "string",

"createdAt": "string",

"updatedAt": "string"

}

}

GET

/api/api-keys/{id}

Playground

Variables

Key

Value

id*

Samples

---

Delete API Key

DELETE

/api/api-keys/{id}

Permanently delete an API key.

Parameters

Path Parameters

id*

Typestring

Required

Responses

API key deleted

DELETE

/api/api-keys/{id}

Playground

Variables

Key

Value

id*

Samples

---

Update API Key

PATCH

/api/api-keys/{id}

Update an API key's name, status, permissions, or modules.

Parameters

Path Parameters

id*

Typestring

Required

Request Body

application/json

{

"name": "string",

"enabled": true,

"permissions": [

"string"

],

"modules": [

"string"

]

}

Responses

API key updated

Content-Type

application/json

{

"data": {

"id": "string",

"name": "string",

"prefix": "string",

"start": "string",

"organizationId": "string",

"enabled": true,

"permissions": [

"string"

],

"modules": [

"string"

],

"expiresAt": "string",

"createdAt": "string",

"updatedAt": "string"

}

}

PATCH

/api/api-keys/{id}

Playground

Variables

Key

Value

id*

Body

Samples

---

Powered by VitePress OpenAPI