{"components":{"schemas":{"Error":{"properties":{"detail":{"properties":{"code":{"type":"string"}},"type":"object"}},"type":"object"},"Report":{"properties":{"charge":{"enum":["pending","held","settled","released"],"type":"string"},"created_at":{"format":"date-time","type":"string"},"credits":{"type":"integer"},"family":{"type":"string"},"id":{"format":"uuid","type":"string"},"label":{"type":"string"},"language":{"type":"string"},"pdf":{"description":"The PDF can be fetched","type":"boolean"},"progress":{"properties":{"done":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"replay":{"description":"Only on create: the order already existed for this Idempotency-Key","type":"boolean"},"state":{"enum":["queued","running","done","failed","expired"],"type":"string"}},"type":"object"}},"securitySchemes":{"ApiKey":{"in":"header","name":"X-API-Key","type":"apiKey"}}},"info":{"description":"Readings in ten languages as PDF, ordered with a customer key (X-API-Key) of a workspace with API access. Keys and credits are managed in the portal.","title":"Zenadira report API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/v1/report-templates":{"get":{"operationId":"P01","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"available":{"type":"boolean"},"templates":{"items":{"properties":{"credits":{"type":"integer"},"family":{"type":"string"},"kind":{"type":"string"},"languages":{"items":{"type":"string"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Templates"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid customer key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Scope denied, tenant-admin credential, or the workspace has not activated API access (api_level_required)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Report service disabled or unavailable, or readings cannot be produced right now (reports_unavailable)"}},"security":[{"ApiKey":[]}],"summary":"List the report types, languages and credit prices"}},"/v1/reports":{"get":{"operationId":"P03","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"reports":{"items":{"$ref":"#/components/schemas/Report"},"type":"array"}},"type":"object"}}},"description":"Orders"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid customer key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Scope denied, tenant-admin credential, or the workspace has not activated API access (api_level_required)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Report service disabled or unavailable, or readings cannot be produced right now (reports_unavailable)"}},"security":[{"ApiKey":[]}],"summary":"List recent report orders (newest first, up to 50)"},"post":{"description":"Requires a customer key with jobs:write. Birth data is computed first, so invalid input never holds credits; then the price of the template is held on the workspace credits and the reading is produced in the background (usually a few minutes). A finished reading is charged in full; a failed one releases the hold. The same Idempotency-Key with the same body returns the existing order (200, replay true); with a different body it answers 409. Report credits come from the workspace balance, not from the key limit.","operationId":"P02","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":8,"pattern":"^[A-Za-z0-9._-]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"natal and human-design need date, time, latitude, longitude and timezone; synastry needs them with the prefixes a_ and b_; numerology needs date (birth_name recommended).","properties":{"a_date":{"description":"Local birth date (YYYY-MM-DD)","format":"date","type":"string"},"a_latitude":{"description":"Degrees, north positive","type":["string","number"]},"a_longitude":{"description":"Degrees, east positive","type":["string","number"]},"a_place":{"maxLength":64,"type":"string"},"a_time":{"description":"Local birth time (HH:MM)","pattern":"^\\d{2}:\\d{2}$","type":"string"},"a_timezone":{"description":"IANA time zone, for example Europe/Vienna","type":"string"},"b_date":{"description":"Local birth date (YYYY-MM-DD)","format":"date","type":"string"},"b_latitude":{"description":"Degrees, north positive","type":["string","number"]},"b_longitude":{"description":"Degrees, east positive","type":["string","number"]},"b_place":{"maxLength":64,"type":"string"},"b_time":{"description":"Local birth time (HH:MM)","pattern":"^\\d{2}:\\d{2}$","type":"string"},"b_timezone":{"description":"IANA time zone, for example Europe/Vienna","type":"string"},"birth_name":{"description":"Numerology: full birth name","maxLength":120,"type":"string"},"date":{"description":"Local birth date (YYYY-MM-DD)","format":"date","type":"string"},"family":{"enum":["natal","human-design","numerology","synastry"],"type":"string"},"label":{"description":"Your reference for the order, shown in the studio list","maxLength":120,"type":"string"},"language":{"enum":["de","en","pt","es","fr","it","pl","cs","nl","sv"],"type":"string"},"latitude":{"description":"Degrees, north positive","type":["string","number"]},"longitude":{"description":"Degrees, east positive","type":["string","number"]},"name":{"description":"Name shown in the reading (optional)","maxLength":80,"type":"string"},"name_b":{"description":"Synastry: name of the second person","maxLength":80,"type":"string"},"place":{"maxLength":64,"type":"string"},"time":{"description":"Local birth time (HH:MM)","pattern":"^\\d{2}:\\d{2}$","type":"string"},"timezone":{"description":"IANA time zone, for example Europe/Vienna","type":"string"}},"required":["family","language"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}},"description":"Existing order for this Idempotency-Key"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}},"description":"Order accepted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON or Idempotency-Key"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid customer key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not enough credits (insufficient_credits)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Scope denied, tenant-admin credential, or the workspace has not activated API access (api_level_required)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Idempotency-Key reused with a different body"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid_family, invalid_language, invalid_label, missing_birth_data, invalid_input or input_rejected"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Report service disabled or unavailable, or readings cannot be produced right now (reports_unavailable)"}},"security":[{"ApiKey":[]}],"summary":"Order a reading"}},"/v1/reports/{id}":{"get":{"operationId":"P04","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}},"description":"Order"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid customer key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Scope denied, tenant-admin credential, or the workspace has not activated API access (api_level_required)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unknown order or another workspace"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Report service disabled or unavailable, or readings cannot be produced right now (reports_unavailable)"}},"security":[{"ApiKey":[]}],"summary":"Get the state of a report order"}},"/v1/reports/{id}/pdf":{"get":{"operationId":"P05","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"The PDF"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid customer key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Scope denied, tenant-admin credential, or the workspace has not activated API access (api_level_required)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unknown order or another workspace"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not finished yet or expired (report_not_ready)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Report service disabled or unavailable, or readings cannot be produced right now (reports_unavailable)"}},"security":[{"ApiKey":[]}],"summary":"Download the finished reading as PDF"}}},"servers":[{"url":"https://api.astro.bitwalker.cloud"}]}