Oracle API Documentation

Everything you need to integrate spiritual insights and personalized oracle readings into your own apps.

Documentation

Get Started Authentication Readings Gifts Error Codes

Get Started

Connect your applications to Yes No Oracle with a simple REST API. Retrieve your readings, manage your history and offer readings as gifts, all in a few JSON requests. This documentation covers authentication, available endpoints and error codes.

All responses are JSON. Authenticated endpoints require your personal API key passed as a Bearer token.

Authentication

All authenticated endpoints require an Authorization header containing your API key, which you can generate from your account settings.

Base URL

TEXT

https://www.yes-no-oracle.com/api/v1

BASH

curl -X GET "https://www.yes-no-oracle.com/api/v1/readings" \
  -H "Authorization: Bearer yno_your_api_key"

Keep your key private

Never expose your API key in client-side code (browser, mobile app). Always make API calls from a secure server.

Readings

Retrieve, update, or delete readings saved to your account. All endpoints require authentication.

List Readings

Returns your readings in reverse chronological order, with cursor-based pagination.

GEThttps://www.yes-no-oracle.com/api/v1/readings

Parameter	Type	Description
`limit`	number	Number of results per page (default: 50, max: 100).
`cursor`	string	Pagination cursor — use the nextCursor value from the previous response.

BASH

curl "https://www.yes-no-oracle.com/api/v1/readings?limit=10" \
  -H "Authorization: Bearer yno_your_api_key"

JSON

{
  "data": [
    {
      "id": "clx...",
      "readingTypeId": "destiny",
      "cards": [...],
      "note": "This spoke to me deeply.",
      "mood": "inspired",
      "customTitle": null,
      "cardCount": 3,
      "createdAt": "2026-04-28T14:23:00.000Z"
    }
  ],
  "nextCursor": "clx..."
}

Get a Reading

Retrieve a single reading by its ID.

GEThttps://www.yes-no-oracle.com/api/v1/readings/:id

BASH

curl "https://www.yes-no-oracle.com/api/v1/readings/clx..." \
  -H "Authorization: Bearer yno_your_api_key"

JSON

{
  "data": {
    "id": "clx...",
    "readingTypeId": "love",
    "cards": [...],
    "note": null,
    "mood": "hopeful",
    "createdAt": "2026-04-28T14:23:00.000Z"
  }
}

Update a Reading

Update the note and/or mood of an existing reading.

PATCHhttps://www.yes-no-oracle.com/api/v1/readings/:id

Parameter	Type	Description
`note`	string	Optional. Personal note attached to the reading.
`mood`	string	Optional. Mood tag for the reading.

BASH

curl -X PATCH "https://www.yes-no-oracle.com/api/v1/readings/clx..." \
  -H "Authorization: Bearer yno_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Updated thoughts." }'

Delete a Reading

Permanently delete a reading from your account.

DELETEhttps://www.yes-no-oracle.com/api/v1/readings/:id

BASH

curl -X DELETE "https://www.yes-no-oracle.com/api/v1/readings/clx..." \
  -H "Authorization: Bearer yno_your_api_key"

JSON

{ "data": { "success": true } }

Gifts

Exclusive Access

Send oracle readings as gifts. Each gift generates a unique link valid indefinitely. Limited to 3 gifts per 24 hours.

List Recent Gifts

Returns gifts created in the last 24 hours.

GEThttps://www.yes-no-oracle.com/api/v1/gifts

BASH

curl "https://www.yes-no-oracle.com/api/v1/gifts" \
  -H "Authorization: Bearer yno_your_api_key"

JSON

{
  "data": [
    {
      "id": "clx...",
      "readingTypeId": "love",
      "token": "a3f9b...",
      "sentAt": "2026-05-01T08:00:00.000Z",
      "isUsed": false,
      "recipientEmail": null,
      "url": "https://www.yes-no-oracle.com/gift/a3f9b..."
    }
  ]
}

Create a Gift

Generate a new gift token for a given reading type.

readingTypeId	Reading
`destiny`	Destiny Reading
`love`	Love Reading
`guardian-angel`	Guardian Angel Reading
`life-purpose`	Life Purpose Reading
`relationship`	Relationship Reading
`fortune`	Fortune Reading
`guidance`	Guidance Reading
`health`	Health Reading

POSThttps://www.yes-no-oracle.com/api/v1/gifts

Parameter	Type	Description
`readingTypeId`required	string	Required. The reading type to gift (see table above).
`message`	string	Optional. Personal message included with the gift.

BASH

curl -X POST "https://www.yes-no-oracle.com/api/v1/gifts" \
  -H "Authorization: Bearer yno_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "readingTypeId": "love",
    "message": "Thinking of you — here is a little something."
  }'

JSON

{
  "data": {
    "id": "clx...",
    "token": "a3f9b...",
    "readingTypeId": "love",
    "sentAt": "2026-05-01T09:00:00.000Z",
    "url": "https://www.yes-no-oracle.com/gift/a3f9b..."
  }
}

Error Codes

Oracle API uses standard HTTP status codes. Error responses always include an error field with a human-readable message.

Code	Meaning
200	Request succeeded.
201	Resource created successfully.
400	Bad request — missing or invalid parameters.
401	Unauthorized — missing or invalid API key.
403	Forbidden — VIP subscription required.
404	Resource not found.
429	Rate limit exceeded.
500	Internal server error.

JSON

{
  "error": "VIP subscription required"
}