Test Oracle Connection

Probes a price-oracle connection without saving anything, through the same reader the platform uses for real reads. Use it while configuring an oracle, before Create Oracle or Update Oracle.

• For TEFAS and TOGG a code is required and that one series is read.
• For SHEET with no code, the whole tab is loaded and parsed; with a code, that row is read.

A probe that reaches the source and comes back wrong is still a 200, with ok: false and the reason in error. The response never contains what the source sent back: error says only whether the source answered and with which status.

Reusing a stored secret. Set oracle_id and omit connection.auth.secret (or send null) to probe with the secret stored on that oracle. The stored secret is only sent to the origin (scheme, host and port) it was saved for; probing another origin with it is refused with 10002 (domain 83). Send the secret in the request to test another host.

Allowed targets. The URL must be public https, or an in-cluster host the environment lists. Plain http on the internet, private addresses and the cloud metadata endpoint are refused with 10001 (domain 83) before anything is sent.

Required permission: oracle:update

Request

POST /v2/admin/oracles/test-connection

Headers

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

Body

Field	Type	Required	Description
oracle_id	string | null	No	Id of a stored oracle whose secret fills an omitted connection.auth.secret
type	string	Yes	Source type: TEFAS, TOGG or SHEET
code	string	Conditional	Series to read. Required for TEFAS and TOGG; optional for SHEET
connection	object	Yes	The connection to probe, with the same fields as on Create Oracle (url, timeout, cache_ttl_seconds, auth, headers)

Example

curl --request POST \
  --url '{{baseUrl}}/v2/admin/oracles/test-connection' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "oracle_id": "677ed6e3cc111aea14a3dfc3",
    "type": "TEFAS",
    "code": "IOG",
    "connection": {
      "url": "https://tefas-api.p.rapidapi.com",
      "timeout": 30,
      "auth": { "type": "API_KEY", "name": "x-rapidapi-key", "secret": null },
      "headers": [
        { "name": "x-rapidapi-host", "value": "tefas-api.p.rapidapi.com" }
      ]
    }
  }'

Response

A working connection:

{
  "ok": true,
  "latency_ms": 412
}

A source that answered with an error:

{
  "ok": false,
  "latency_ms": 198,
  "error": "the source answered HTTP 404"
}

Response Fields

Field	Type	Description
ok	boolean	Whether the probe read data the provider understands
latency_ms	integer	Duration of the probe in milliseconds
error	string	Only when ok is false: the source answered HTTP <status>, the source could not be reached, or the source answered, but not with data this provider can read

Errors

Status	Code	Description
400	10015	Validation failed — see details
400	10000	oracle_id is not a valid 24-character hex id
400	10001	The oracle named by oracle_id was not found (domain 5)
400	-1	The connection is incomplete (URL scheme, or the auth scheme's name, username or secret missing), or code is missing for TEFAS / TOGG
400	10001	Target refused: not https, does not resolve, or resolves to a private or metadata address (domain 83)
400	10002	The stored secret would be sent to a host other than the one it is stored for (domain 83)

See Errors for the error format and common codes.