{ "openapi": "3.1.0", "info": { "title": "Safra Partner API", "version": "2026-08-21", "description": "Machine-to-machine API for verified Safra companies. Authenticate with a company secret key (`sk_live_\u2026`) from the company dashboard Developers tab. The company is implicit from the key \u2014 paths never include `{company}`." }, "servers": [ { "url": "/api/partner/v1", "description": "Partner API v1" } ], "tags": [ { "name": "Reference" }, { "name": "Company" }, { "name": "Members" }, { "name": "Fleet" }, { "name": "Trips" }, { "name": "Schedules" }, { "name": "Bookings" }, { "name": "Payments" }, { "name": "Reports" }, { "name": "Reviews" }, { "name": "Webhooks" } ], "paths": { "/openapi.json": { "get": { "summary": "OpenAPI specification", "tags": [ "Reference" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document" } } } }, "/cities": { "get": { "summary": "List trip cities", "tags": [ "Reference" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/places": { "get": { "summary": "Search places", "tags": [ "Reference" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/company": { "get": { "summary": "Get authenticated company", "tags": [ "Company" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "patch": { "summary": "Update company profile", "tags": [ "Company" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/company/logo": { "post": { "summary": "Upload company logo (base64)", "tags": [ "Company" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Remove company logo", "tags": [ "Company" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/members": { "get": { "summary": "List members", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Add member by phone", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/members/{memberId}": { "patch": { "summary": "Update member role", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Remove member", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/vehicles": { "get": { "summary": "List fleet", "tags": [ "Fleet" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Create vehicle", "tags": [ "Fleet" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/vehicles/{vehicleId}": { "patch": { "summary": "Update vehicle", "tags": [ "Fleet" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Delete vehicle", "tags": [ "Fleet" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "vehicleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/trips": { "get": { "summary": "List trips", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Publish a trip", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/trips/{tripId}": { "get": { "summary": "Get trip", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "tripId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update trip", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "tripId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Cancel trip", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "tripId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/trips/{tripId}/complete": { "post": { "summary": "Complete trip", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "tripId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/trips/{tripId}/manifest": { "get": { "summary": "Trip passenger manifest", "tags": [ "Trips" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "tripId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/schedules": { "get": { "summary": "List schedules", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Create schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/schedules/{scheduleId}": { "get": { "summary": "Get schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Deactivate schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/schedules/{scheduleId}/toggle": { "post": { "summary": "Pause or resume schedule", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/schedules/{scheduleId}/exceptions": { "post": { "summary": "Upsert schedule exception", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/schedules/{scheduleId}/exceptions/{exceptionId}": { "delete": { "summary": "Delete schedule exception", "tags": [ "Schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "exceptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/bookings": { "get": { "summary": "List bookings", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Create booking by passenger phone", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/bookings/{bookingId}": { "get": { "summary": "Get booking", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Approve, reject, or cancel a booking", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/bookings/{bookingId}/boarded": { "post": { "summary": "Mark passenger boarded", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/bookings/{bookingId}/no-show": { "post": { "summary": "Mark passenger no-show", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/bookings/{bookingId}/ticket": { "get": { "summary": "Boarding ticket payload", "tags": [ "Bookings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/payments": { "get": { "summary": "List payments", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/payments/{paymentId}": { "get": { "summary": "Get payment", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/payments/{paymentId}/invoice.pdf": { "get": { "summary": "Download payment invoice PDF", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/payouts": { "get": { "summary": "Company payout statement", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/dashboard": { "get": { "summary": "Operations dashboard summary", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/reports": { "get": { "summary": "Filtered company report", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/reports/export": { "get": { "summary": "Export report CSV/XLSX/PDF", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/reviews": { "get": { "summary": "List company reviews", "tags": [ "Reviews" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/webhooks": { "get": { "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Create webhook endpoint", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/webhooks/{endpointId}": { "patch": { "summary": "Update webhook endpoint", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Delete webhook endpoint", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/webhooks/{endpointId}/test": { "post": { "summary": "Queue a test ping", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/webhooks/{endpointId}/deliveries": { "get": { "summary": "List deliveries for an endpoint", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Company API key: `Authorization: Bearer sk_live_\u2026`" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Replay-safe key for POST/PATCH/PUT/DELETE. Replayed responses include `Idempotency-Replayed: true`." } } } }