{"openapi":"3.1.0","info":{"title":"CloudTalk Networks Masking API","description":"Create a session between two parties, get a masked number, and we route the call privately. Authenticate every request with the `X-API-Key` header from your CloudTalk Networks dashboard.","version":"0.1.0"},"paths":{"/v1/did/assignments":{"get":{"tags":["tenant"],"summary":"Tenant List Assigned Dids","description":"List this tenant's DID assignments.\n\nBy default only **active** assignments are returned — that's the tenant's\ncurrent usable inventory. Released DIDs are kept in our database for audit\nand billing history; pass ``?status=released`` to see them, or\n``?status=all`` to see everything.","operationId":"tenant_list_assigned_dids_v1_did_assignments_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"status","in":"query","required":false,"schema":{"enum":["active","released","suspended","all"],"type":"string","description":"Filter by assignment status. Defaults to ``active`` so released (historical) DIDs are hidden from the day-to-day view. Pass ``released`` to see history, or ``all`` for everything.","default":"active","title":"Status"},"description":"Filter by assignment status. Defaults to ``active`` so released (historical) DIDs are hidden from the day-to-day view. Pass ``released`` to see history, or ``all`` for everything."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sessions":{"post":{"tags":["tenant"],"summary":"Post Session","operationId":"post_session_v1_sessions_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["tenant"],"summary":"List Sessions","operationId":"list_sessions_v1_sessions_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sessions/{session_ref}":{"get":{"tags":["tenant"],"summary":"Get Session","operationId":"get_session_v1_sessions__session_ref__get","parameters":[{"name":"session_ref","in":"path","required":true,"schema":{"type":"string","title":"Session Ref"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sessions/{session_ref}/complete":{"post":{"tags":["tenant"],"summary":"Complete Session","operationId":"complete_session_v1_sessions__session_ref__complete_post","parameters":[{"name":"session_ref","in":"path","required":true,"schema":{"type":"string","title":"Session Ref"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/calls/originate":{"post":{"tags":["tenant"],"summary":"Originate","operationId":"originate_v1_calls_originate_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OriginateBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys":{"get":{"tags":["tenant"],"summary":"Tenant List Api Keys","description":"List API keys for the calling tenant. Plaintext is **never** returned.","operationId":"tenant_list_api_keys_v1_api_keys_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["tenant"],"summary":"Tenant Create Api Key","description":"Mint a new API key for this tenant. The plaintext is shown **only once**.\n\nUse this before revoking your current key to avoid lockout.","operationId":"tenant_create_api_key_v1_api_keys_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys/{api_key_id}/rotate":{"post":{"tags":["tenant"],"summary":"Tenant Rotate Api Key","description":"Rotate an API key: revoke the old one and return a freshly minted plaintext.\n\nThe new plaintext is shown **only once**. Update your client config before any\nsubsequent request — the old key stops working immediately.","operationId":"tenant_rotate_api_key_v1_api_keys__api_key_id__rotate_post","parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","title":"Api Key Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys/{api_key_id}/revoke":{"post":{"tags":["tenant"],"summary":"Tenant Revoke Api Key","description":"Revoke a specific API key.\n\nReturns ``409`` if this would leave the tenant with **zero** active keys —\ncreate a new one first, then revoke this one.","operationId":"tenant_revoke_api_key_v1_api_keys__api_key_id__revoke_post","parameters":[{"name":"api_key_id","in":"path","required":true,"schema":{"type":"string","title":"Api Key Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"CreateApiKeyBody":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Label","description":"Optional human-readable label, e.g. 'staging' or 'mobile-backend'."}},"type":"object","title":"CreateApiKeyBody"},"CreateSessionBody":{"properties":{"order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Id"},"driver_phone":{"type":"string","title":"Driver Phone","description":"E.164"},"customer_phone":{"type":"string","title":"Customer Phone","description":"E.164"},"ttl_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ttl Minutes"},"masked_e164":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Masked E164","description":"Optional tenant-assigned masked DID (E.164). Must exist in pool, belong to this tenant, and have no open session on that number."}},"type":"object","required":["driver_phone","customer_phone"],"title":"CreateSessionBody"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OriginateBody":{"properties":{"session_id":{"type":"string","title":"Session Id"},"bill_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Id"},"callee_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callee Id"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"state_callback":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Callback"},"state_callback_events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"State Callback Events"}},"type":"object","required":["session_id"],"title":"OriginateBody"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"TenantApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Per-tenant API key issued by CloudTalk Networks."}}},"tags":[{"name":"tenant","description":"Sessions and call origination for masked calling."},{"name":"DID","description":"Inspect masked numbers assigned to your tenant."}],"security":[{"TenantApiKey":[]}]}