Create Oracle

Registers a price oracle. Every oracle carries its own connection: the provider type does not imply an endpoint.

The connection is checked for completeness before it is saved (an http:// or https:// URL, and the name, username or secret its auth scheme needs). No request is sent to the source here; probe it first with Test Oracle Connection.

connection.auth.secret is write-only: it is stored, never returned, and the response reports only secret_set.

Required permission: oracle:create

Request

POST /v2/admin/oracles

Headers

Name	Description
Authorization	Required. Bearer <access_token>
Content-Type	Required. application/json

Body

Field	Type	Required	Description
category_id	string	Yes	Category the oracle belongs to (24-character hex id). It is not checked to exist
type	string	Yes	Source type: TEFAS, TOGG or SHEET
name	string	Yes	Oracle name
description	string	No	Description
fiat_currency	string	Yes	ISO 4217 code of the currency the source prices in (e.g. TRY). The summary expresses its prices in the active currency token of this currency
codes	array	No	The series this oracle can price
codes[].code	string	Yes	Code the source knows the series by
codes[].name	string	Yes	Display name of the series
codes[].description	string	No	Description of the series
connection	object	Yes	Where the oracle reads from
connection.url	string	Yes	Base URL of the source, starting with http:// or https://. The provider appends only its own resource path
connection.timeout	integer	No	Request timeout in seconds, 0–300. 0 means the default (30)
connection.cache_ttl_seconds	integer	No	How long a fetched source document is reused within one server process, 0–86400. 0 disables this cache
connection.auth	object	No	How the source is authenticated. Omitted means NONE
connection.auth.type	string	No	NONE (public source), BEARER (Authorization: Bearer <secret>), API_KEY (secret in the header named name), BASIC (username + secret) or QUERY_PARAM (secret in the query parameter named name)
connection.auth.name	string	Conditional	Header or query parameter name. Required for API_KEY and QUERY_PARAM
connection.auth.username	string	Conditional	Required for BASIC
connection.auth.secret	string	Conditional	Bearer token, API key or basic password. Required for every scheme except NONE; discarded for NONE
connection.headers	array	No	Static headers sent with every request. Stored and returned in clear text, so never put a credential here
connection.headers[].name	string	Yes	Header name
connection.headers[].value	string	No	Header value
summary_cache_ttl_seconds	integer	No	How long a computed summary is cached, 0–2592000 seconds. 0 means the platform default (12 hours)

Example

curl --request POST \
  --url '{{baseUrl}}/v2/admin/oracles' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "category_id": "677ed6e3cc111aea14a3dfb4",
    "type": "TEFAS",
    "name": "Gümüş Fonu",
    "description": "TEFAS Gümüş Fonu",
    "fiat_currency": "TRY",
    "codes": [
      { "code": "IOG", "name": "Gümüş Fonu" }
    ],
    "connection": {
      "url": "https://tefas-api.p.rapidapi.com",
      "timeout": 30,
      "cache_ttl_seconds": 0,
      "auth": { "type": "API_KEY", "name": "x-rapidapi-key", "secret": "<rapidapi_key>" },
      "headers": [
        { "name": "x-rapidapi-host", "value": "tefas-api.p.rapidapi.com" }
      ]
    },
    "summary_cache_ttl_seconds": 0
  }'

Response

201 Created with the new oracle. The secret is not echoed back.

{
  "id": "6911b0d4e4b0f51d2c8a7e52",
  "category_id": "677ed6e3cc111aea14a3dfb4",
  "type": "TEFAS",
  "name": "Gümüş Fonu",
  "description": "TEFAS Gümüş Fonu",
  "integration": {
    "codes": [
      { "code": "IOG", "name": "Gümüş Fonu" }
    ],
    "fiat_currency": "TRY",
    "connection": {
      "url": "https://tefas-api.p.rapidapi.com",
      "timeout": 30,
      "cache_ttl_seconds": 0,
      "auth": {
        "type": "API_KEY",
        "name": "x-rapidapi-key",
        "username": "",
        "secret_set": true
      },
      "headers": [
        { "name": "x-rapidapi-host", "value": "tefas-api.p.rapidapi.com" }
      ]
    },
    "summary_cache_ttl_seconds": 0,
    "default_summary_cache_ttl_seconds": 43200
  },
  "created_at": "2026-11-09T10:22:05.411Z",
  "updated_at": "2026-11-09T10:22:05.411Z"
}

Response Fields

The oracle, in the shape described on Get Oracle.

Errors

Status	Code	Description
400	10015	Validation failed (a required field missing, type not one of the three, connection.url not a URL, a number out of range, an unknown auth.type) — see details
400	-1	The connection is incomplete: the URL does not start with http:// or https://, or the auth scheme is missing its name, username or secret. message names which

See Errors for the error format and common codes.