Tarot Spread Reading

POST

/interpret/tarot

curl -X POST https://api.astroway.info/v1/interpret/tarot \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "deck": "rider-waite", "spread": "three-card", "question": "What should I focus on at work?", "cards": [ "the-fool", { "slug": "4-of-cups", "reversed": true }, "the-sun" ], "language": "en" }'

const res = await fetch('https://api.astroway.info/v1/interpret/tarot', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "deck": "rider-waite",
    "spread": "three-card",
    "question": "What should I focus on at work?",
    "cards": [
      "the-fool",
      {
        "slug": "4-of-cups",
        "reversed": true
      },
      "the-sun"
    ],
    "language": "en"
  }),
});
const { ok, data, error } = await res.json();
if (!ok) throw new Error(error.message);
console.log(data);

import os, requests

r = requests.post(
    'https://api.astroway.info/v1/interpret/tarot',
    headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY'], 'Content-Type': 'application/json'},
    json={
      'deck': "rider-waite",
      'spread': "three-card",
      'question': "What should I focus on at work?",
      'cards': [
        "the-fool",
        {
          'slug': "4-of-cups",
          'reversed': True
        },
        "the-sun"
      ],
      'language': "en"
    },
)
result = r.json()
if not result['ok']:
    raise RuntimeError(result['error']['message'])
print(result['data'])

<?php
use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
$r = $client->post('interpret/tarot', [
    'headers' => ['X-Api-Key' => getenv('ASTROWAY_API_KEY')],
    'json' => [
        'deck' => 'rider-waite',
        'spread' => 'three-card',
        'question' => 'What should I focus on at work?',
        'cards' => ['the-fool', [
            'slug' => '4-of-cups',
            'reversed' => true,
        ], 'the-sun'],
        'language' => 'en',
    ],
]);
$result = json_decode($r->getBody(), true);
if (!$result['ok']) throw new \RuntimeException($result['error']['message']);
print_r($result['data']);

AI reading of a tarot, Marseille or Lenormand spread: each position read in context, then a synthesis of the whole spread and one piece of advice. Takes card slugs or the drawn array of any draw response. Multi-language.

Authorizations

ApiKeyAuth

Parameters

Header Parameters

Accept-Language

string

Allowed values: uk en de ru pl es pt fr it nl cs ro hu el tr ar hi ja ko vi id

Target language for response text fields. RFC 7231 q-weighted. Falls back to ?lang= query param, then body.language, then source uk. Unknown codes silently fall through to uk.

Example

de

X-Provider

string

Allowed values: openai anthropic google groq mistral openrouter deepseek together

Bring your own model key: the LLM provider that should run this completion. Send together with X-Provider-Key or the request is refused: a key with no provider bills us for tokens you meant to pay for, and a provider with no key would look like it worked. The endpoint is fixed per provider on our side and is never taken from the request. There is no fallback to our own chain: if your key fails you get the provider’s status and message.

Example

anthropic

X-Provider-Key

string

Your own credential for X-Provider. Never logged, stored or cached: it travels in a header because the request body is hashed into two cache keys, and a BYOK turn bypasses both caches in each direction. A provider error that quotes the key back is redacted before it reaches our logs or your response. Such a turn costs 5 credits instead of the endpoint price, and only when a completion actually ran on your key.

Example

sk-ant-...

X-Provider-Model

string

<= 120 characters

Optional model id, overriding the default for that provider. Defaults: openai → gpt-4o-mini, anthropic → claude-sonnet-4-5, google → gemini-2.5-flash, groq → openai/gpt-oss-120b, mistral → mistral-large-latest, openrouter → meta-llama/llama-3.3-70b-instruct, deepseek → deepseek-chat, together → meta-llama/Llama-3.3-70B-Instruct-Turbo.

Example

claude-sonnet-4-5

Query Parameters

lang

string

Allowed values: uk en de ru pl es pt fr it nl cs ro hu el tr ar hi ja ko vi id

Alternative to Accept-Language for clients without header control.

Example

hi

fields

string

Comma-separated dotted paths, relative to data, to keep in the response. A path is applied to every element of an array, so planets.name means the name of each planet. Paths that match nothing come back in _fields_unmatched; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer.

Example

planets.name,planets.longitude

precision

integer

<= 15

Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute.

Example

Request Body^required

application/json

object

deck

string

default: rider-waite

Allowed values: rider-waite marseille lenormand

spread

string

<= 60 characters

cards required

Array

>= 1 items <= 36 items

Any of:

string

>= 1 characters <= 80 characters

question

string

<= 500 characters

language

string

Allowed values: uk en de pl es pt fr it nl cs ro hu el tr ar hi ja ko vi id ru

art

Card art set for the images in the answer. GET /v1/tarot/decks lists them.

string

<= 40 characters

Example

{
  "deck": "rider-waite",
  "spread": "three-card",
  "question": "What should I focus on at work?",
  "cards": [
    "the-fool",
    {
      "slug": "4-of-cups",
      "reversed": true
    },
    "the-sun"
  ],
  "language": "en"
}

Responses

200

Successful calculation

application/json

object

boolean

data

object

deck

string

nullable

spread

object

slug

string

nullable

name

string

nullable

question

string

nullable

positions

Array<object>

nullable

object

index

number

nullable

position

string

nullable

positionMeaning

string

nullable

card

object

slug

string

nullable

name

string

nullable

reversed

boolean

nullable

reading

string

nullable

synthesis

string

nullable

advice

string

nullable

disclaimer

string

nullable

model

string

nullable

language

string

nullable

Example

{
  "ok": true,
  "data": {
    "deck": "rider-waite",
    "spread": {
      "slug": "three-card",
      "name": "Past / Present / Future"
    },
    "question": "What should I focus on at work?",
    "positions": [
      {
        "index": 0,
        "position": "Past",
        "positionMeaning": "Forces from the past shaping the situation.",
        "card": {
          "slug": "the-fool",
          "name": "The Fool"
        },
        "reversed": false,
        "reading": "The Fool in the past speaks of a leap you already took…"
      }
    ],
    "synthesis": "Read together, the cards…",
    "advice": "…",
    "disclaimer": "…",
    "model": "…",
    "language": "en"
  }
}

400

Validation error

application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Date must be YYYY-MM-DD",
    "details": [
      {
        "path": "date",
        "message": "Date must be YYYY-MM-DD"
      }
    ]
  }
}

401

Missing or invalid API key

application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Корисно?

Запропонувати правку

// Назад

Specific Placement Interpretation

Далі //

Overview

Tarot Spread Reading

Authorizations

Parameters

Header Parameters

Example

Example

Example

Example

Query Parameters

Example

Example

Example

Request Body required

Example

Responses

200

Example

400

Example

401

Example

Request Body^required