{ "openapi": "3.0.0", "info": { "title": "Magpie Meetings API", "version": "1.0.0", "description": "Bookings, availability, Notes, teams, Dashboard, Contacts, To-dos, invoices, Forms, Spreadsheets, Websites, Issues, Store, Courses, Integrations, calendar and chat. See docs/API_V1.md for authorization and mobile session contracts.", "contact": { "name": "Magpie Meetings", "url": "https://magpie.diy" } }, "servers": [ { "url": "https://magpie.diy/api/v1", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Token" } }, "schemas": { "StoreApiCustomer": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "email": {"type": "string", "nullable": true}, "name": {"type": "string", "nullable": true}, "phone": {"type": "string", "nullable": true}, "order_count": {"type": "integer"}, "total_spent_amount": {"type": "integer"}, "refunded_amount": {"type": "integer"}, "currency": {"type": "string"}, "first_order_at": {"type": "string", "format": "date-time", "nullable": true}, "last_order_at": {"type": "string", "format": "date-time", "nullable": true}, "tags": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "string", "nullable": true}, "marketing_consent": {"type": "string", "enum": ["unknown", "granted", "declined"]}, "marketing_consent_at": {"type": "string", "format": "date-time", "nullable": true}, "erased": {"type": "boolean", "description": "The customer's personal data was erased; totals are kept."}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time", "nullable": true}}, "required": ["uuid", "order_count", "total_spent_amount", "currency"], "description": "One profile per buyer email per Store. Totals count paid orders; total_spent_amount is what they paid less succeeded refunds, in minor units."}, "StoreApiCustomerDetail": {"allOf": [{"$ref": "#/components/schemas/StoreApiCustomer"}, {"type": "object", "properties": {"addresses": {"type": "array", "items": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string", "nullable": true}, "line1": {"type": "string", "nullable": true}, "line2": {"type": "string", "nullable": true}, "city": {"type": "string", "nullable": true}, "state": {"type": "string", "nullable": true}, "postal_code": {"type": "string", "nullable": true}, "country": {"type": "string", "nullable": true}, "last_used_at": {"type": "string", "format": "date-time", "nullable": true}}}}, "orders": {"type": "array", "description": "Newest first, up to 100.", "items": {"$ref": "#/components/schemas/StoreApiOrder"}}}}]}, "StoreApiAddress": {"type": "object", "properties": {"name": {"type": "string", "nullable": true}, "line1": {"type": "string", "nullable": true}, "line2": {"type": "string", "nullable": true}, "city": {"type": "string", "nullable": true}, "state": {"type": "string", "nullable": true}, "postal_code": {"type": "string", "nullable": true}, "country": {"type": "string", "nullable": true}}, "description": "Every field is present; empty fields are null. country is an ISO 3166-1 alpha-2 code."}, "StoreApiDiscount": {"type": "object", "description": "A Store discount (StoreDiscountService). Money is minor units of the Store's currency; percent_basis_points is 100 for 1%. starts_at and ends_at are UTC.", "properties": {"uuid": {"type": "string", "format": "uuid"}, "method": {"type": "string", "enum": ["code", "automatic"]}, "code": {"type": "string", "nullable": true}, "title": {"type": "string"}, "status": {"type": "string", "enum": ["draft", "active", "archived"]}, "state": {"type": "string", "enum": ["draft", "scheduled", "active", "ended", "archived"]}, "kind": {"type": "string", "enum": ["percentage", "fixed_amount", "free_shipping", "buy_x_get_y"]}, "percent_basis_points": {"type": "integer", "nullable": true}, "amount_off": {"type": "integer", "nullable": true}, "buy_quantity": {"type": "integer", "nullable": true}, "get_quantity": {"type": "integer", "nullable": true}, "applies_to": {"type": "string", "enum": ["order", "products", "collections"]}, "minimum_type": {"type": "string", "enum": ["none", "subtotal", "quantity"]}, "minimum_subtotal_amount": {"type": "integer", "nullable": true}, "minimum_quantity": {"type": "integer", "nullable": true}, "max_applications_per_order": {"type": "integer", "nullable": true}, "usage_limit": {"type": "integer", "nullable": true}, "per_customer_limit": {"type": "integer", "nullable": true}, "combinable": {"type": "boolean"}, "starts_at": {"type": "string", "format": "date-time"}, "ends_at": {"type": "string", "format": "date-time", "nullable": true}, "summary": {"type": "string"}, "currency": {"type": "string"}, "created_at": {"type": "string", "format": "date-time", "nullable": true}, "updated_at": {"type": "string", "format": "date-time", "nullable": true}, "times_used": {"type": "integer", "description": "List rows only: paid orders that used it."}, "amount_given": {"type": "integer", "description": "List rows only: the total it took off paid orders."}}}, "StoreApiDiscountDetail": {"allOf": [{"$ref": "#/components/schemas/StoreApiDiscount"}, {"type": "object", "properties": {"product_ids": {"type": "array", "items": {"type": "string", "format": "uuid"}}, "collection_ids": {"type": "array", "items": {"type": "string", "format": "uuid"}}, "segment": {"type": "object", "nullable": true, "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}}}, "usage": {"type": "object", "properties": {"times_used": {"type": "integer"}, "held_by_open_checkouts": {"type": "integer"}, "amount_given": {"type": "integer"}}}}}]}, "StoreApiOrderItem": {"type": "object", "properties": {"id": {"type": "integer"}, "product_uuid": {"type": "string", "format": "uuid", "nullable": true}, "variant_uuid": {"type": "string", "format": "uuid", "nullable": true}, "product_name": {"type": "string"}, "variant_title": {"type": "string"}, "options": {"type": "object", "nullable": true, "additionalProperties": true}, "sku": {"type": "string", "nullable": true}, "quantity": {"type": "integer"}, "unit_amount": {"type": "integer"}, "discount_amount": {"type": "integer"}, "tax_amount": {"type": "integer"}, "line_total_amount": {"type": "integer"}, "digital": {"type": "boolean"}, "shipped_quantity": {"type": "integer"}, "remaining_quantity": {"type": "integer"}, "personalisation": {"type": "array", "description": "What the buyer filled in, as shown to them; price_amount is what the field added per unit.", "items": {"type": "object", "properties": {"label": {"type": "string"}, "value": {"type": "string"}, "price_amount": {"type": "integer"}}}}, "pay_what_you_want": {"type": "boolean", "description": "The buyer chose unit_amount, at or above the variant's minimum."}, "backorder_quantity": {"type": "integer", "description": "Units that were not in stock when the order was placed."}, "expected_ship_date": {"type": "string", "format": "date", "nullable": true}, "bundle_parts": {"type": "array", "description": "For a bundle, the parts it was sold with: quantity_per_bundle in one bundle and quantity in the whole line. Empty for other lines.", "items": {"type": "object", "properties": {"product_name": {"type": "string"}, "variant_title": {"type": "string"}, "sku": {"type": "string", "nullable": true}, "quantity_per_bundle": {"type": "integer"}, "quantity": {"type": "integer"}, "backorder_quantity": {"type": "integer"}}}}}, "required": ["id", "product_name", "quantity", "unit_amount", "line_total_amount"], "description": "A line as sold: names, SKU and prices are a snapshot from the time of the order. Amounts are minor units."}, "StoreApiShipment": {"type": "object", "properties": {"id": {"type": "integer"}, "carrier": {"type": "string", "nullable": true}, "tracking_number": {"type": "string", "nullable": true}, "tracking_url": {"type": "string", "nullable": true}, "shipped_at": {"type": "string", "format": "date-time", "nullable": true}, "items": {"type": "array", "items": {"type": "object", "properties": {"item_id": {"type": "integer"}, "product_name": {"type": "string"}, "variant_title": {"type": "string"}, "sku": {"type": "string", "nullable": true}, "quantity": {"type": "integer"}}}}}, "required": ["id", "items"]}, "StoreApiRefund": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "amount": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "succeeded", "failed"]}, "method": {"type": "string", "enum": ["stripe", "manual"]}, "reason": {"type": "string", "nullable": true}, "restock_requested": {"type": "boolean"}, "restock_items": {"type": "array", "items": {"type": "object", "properties": {"item_id": {"type": "integer"}, "quantity": {"type": "integer"}}}}, "restocked_at": {"type": "string", "format": "date-time", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}}, "required": ["uuid", "amount", "status"]}, "StoreApiOrderEvent": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "type": {"type": "string"}, "label": {"type": "string"}, "message": {"type": "string", "nullable": true}, "actor": {"type": "object", "nullable": true, "properties": {"id": {"type": "integer"}, "name": {"type": "string", "nullable": true}}}, "created_at": {"type": "string", "format": "date-time"}}, "required": ["uuid", "type", "label"]}, "StoreApiOrder": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "number": {"type": "string"}, "channel": {"type": "string", "enum": ["online", "manual", "in_person"]}, "payment_state": {"type": "string", "enum": ["pending", "paid", "failed", "canceled", "partially_refunded", "refunded"]}, "payment_method": {"type": "string"}, "fulfillment_state": {"type": "string", "enum": ["unfulfilled", "partially_fulfilled", "fulfilled", "canceled"]}, "dispute_state": {"type": "string", "enum": ["none", "open", "won", "lost"]}, "currency": {"type": "string", "description": "Lowercase ISO 4217 code."}, "subtotal_amount": {"type": "integer"}, "discount_amount": {"type": "integer"}, "discount_code": {"type": "string", "nullable": true}, "shipping_amount": {"type": "integer"}, "shipping_discount_amount": {"type": "integer"}, "tax_amount": {"type": "integer"}, "total_amount": {"type": "integer"}, "refunded_amount": {"type": "integer"}, "item_count": {"type": "integer"}, "customer": {"type": "object", "properties": {"name": {"type": "string", "nullable": true}, "email": {"type": "string", "nullable": true}, "phone": {"type": "string", "nullable": true}}}, "tags": {"type": "array", "items": {"type": "string"}}, "created_at": {"type": "string", "format": "date-time"}, "paid_at": {"type": "string", "format": "date-time", "nullable": true}, "fulfilled_at": {"type": "string", "format": "date-time", "nullable": true}, "canceled_at": {"type": "string", "format": "date-time", "nullable": true}, "updated_at": {"type": "string", "format": "date-time", "nullable": true}}, "required": ["uuid", "number", "payment_state", "fulfillment_state", "currency", "total_amount", "customer"], "description": "An order as listed. Amounts are integer minor units of currency. The customer's details are returned because the caller acts for the seller."}, "StoreApiOrderDetail": {"allOf": [{"$ref": "#/components/schemas/StoreApiOrder"}, {"type": "object", "properties": {"refundable_amount": {"type": "integer"}, "payment_plan": {"type": "object", "nullable": true, "description": "A course's payment plan: the monthly payments agreed, how many were paid, one payment's amount and the total paid so far (tax included), in minor units. Null for other orders.", "properties": {"payments": {"type": "integer"}, "paid_count": {"type": "integer"}, "amount": {"type": "integer"}, "received": {"type": "integer"}}}, "shipping_method": {"type": "string", "nullable": true}, "delivery_date": {"type": "string", "format": "date", "nullable": true, "description": "The local delivery date the customer chose at checkout."}, "ready_for_pickup_at": {"type": "string", "format": "date-time", "nullable": true, "description": "When the seller marked a pickup order ready."}, "shipping_address": {"allOf": [{"$ref": "#/components/schemas/StoreApiAddress"}], "nullable": true}, "billing_address": {"allOf": [{"$ref": "#/components/schemas/StoreApiAddress"}], "nullable": true}, "risk_level": {"type": "string", "nullable": true}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiOrderItem"}}, "shipments": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiShipment"}}, "refunds": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiRefund"}}, "returns": {"type": "array", "items": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "number": {"type": "string"}, "status": {"type": "string"}, "reason": {"type": "string"}, "resolution": {"type": "string", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}}}}, "history": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiOrderEvent"}, "description": "Newest first. Present on GET /store-orders/{uuid}."}}}]}, "StoreApiVariant": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "sku": {"type": "string", "nullable": true}, "barcode": {"type": "string", "nullable": true}, "price_amount": {"type": "integer"}, "compare_at_amount": {"type": "integer", "nullable": true}, "unit_cost_amount": {"type": "integer", "nullable": true}, "is_active": {"type": "boolean"}, "track_inventory": {"type": "boolean"}, "on_hand": {"type": "integer", "nullable": true, "description": "Null when stock is not tracked."}, "reserved": {"type": "integer", "nullable": true, "description": "Held for checkouts in progress."}, "available": {"type": "integer", "nullable": true}, "reorder_point": {"type": "integer", "nullable": true}, "weight_grams": {"type": "integer", "nullable": true}, "updated_at": {"type": "string", "format": "date-time", "nullable": true}}, "required": ["uuid", "title", "price_amount", "track_inventory"]}, "StoreApiProduct": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "slug": {"type": "string"}, "status": {"type": "string", "enum": ["draft", "active", "archived"]}, "product_type": {"type": "string", "enum": ["physical", "digital", "gift_card", "bundle", "course"]}, "requires_shipping": {"type": "boolean"}, "description": {"type": "string", "nullable": true}, "vendor": {"type": "string", "nullable": true}, "category": {"type": "string", "nullable": true}, "tags": {"type": "array", "items": {"type": "string"}}, "published_at": {"type": "string", "format": "date-time", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time", "nullable": true}, "variants": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiVariant"}}}, "required": ["uuid", "title", "status", "variants"]}, "StoreApiInventoryItem": {"allOf": [{"$ref": "#/components/schemas/StoreApiVariant"}, {"type": "object", "properties": {"product": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "status": {"type": "string"}}}, "locations": {"type": "array", "description": "Stock at the default location and each active location holding stock; they add up to on_hand.", "items": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "default": {"type": "boolean"}, "on_hand": {"type": "integer"}}}}}}]}, "MobileSellItem": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "product_uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "sku": {"type": "string", "nullable": true}, "barcode": {"type": "string", "nullable": true}, "price_amount": {"type": "integer"}, "track_inventory": {"type": "boolean"}, "available": {"type": "integer", "nullable": true}, "allow_backorder": {"type": "boolean"}}}, "MobileSellRegister": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["open", "closed"]}, "location": {"type": "object", "properties": {"name": {"type": "string"}}}, "currency": {"type": "string"}, "opened_at": {"type": "string"}, "closed_at": {"type": "string", "nullable": true}, "opening_float_amount": {"type": "integer"}, "sale_count": {"type": "integer"}, "cash_sale_count": {"type": "integer"}, "card_sale_count": {"type": "integer"}, "cash_sales_amount": {"type": "integer"}, "card_sales_amount": {"type": "integer"}, "cash_refunds_amount": {"type": "integer"}, "expected_cash_amount": {"type": "integer"}, "counted_cash_amount": {"type": "integer", "nullable": true}, "difference_amount": {"type": "integer", "nullable": true}, "closing_note": {"type": "string", "nullable": true}}}, "MobileSellSale": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "order_number": {"type": "string"}, "payment_state": {"type": "string"}, "payment_method": {"type": "string", "enum": ["cash", "card"]}, "currency": {"type": "string"}, "subtotal_amount": {"type": "integer"}, "discount_amount": {"type": "integer"}, "total_amount": {"type": "integer"}, "cash_tendered_amount": {"type": "integer", "nullable": true}, "cash_change_amount": {"type": "integer", "nullable": true}, "email": {"type": "string", "nullable": true}, "receipt_sent": {"type": "boolean"}, "receipt_url": {"type": "string", "format": "uri"}, "created_at": {"type": "string"}, "items": {"type": "array", "items": {"type": "object"}}}}, "MobileStockCountVariant": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "product_uuid": {"type": "string", "format": "uuid"}, "product_title": {"type": "string"}, "variant_title": {"type": "string", "nullable": true}, "name": {"type": "string"}, "sku": {"type": "string", "nullable": true}, "barcode": {"type": "string", "nullable": true}, "on_hand": {"type": "integer"}, "reserved": {"type": "integer"}, "countable": {"type": "boolean"}, "not_countable_reason": {"type": "string", "nullable": true, "enum": ["not_tracked", "licence_keys", "archived", "course_seats", null]}}}, "MobileStockCountResponse": {"type": "object", "required": ["data", "replayed"], "properties": {"replayed": {"type": "boolean"}, "data": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "note": {"type": "string", "nullable": true}, "line_count": {"type": "integer"}, "changed_count": {"type": "integer"}, "created_at": {"type": "string", "format": "date-time"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"variant_uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "quantity_before": {"type": "integer"}, "counted_quantity": {"type": "integer"}, "quantity_change": {"type": "integer"}}}}}}}}, "StoreApiReturn": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "number": {"type": "string"}, "order": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "number": {"type": "string"}}}, "status": {"type": "string", "enum": ["requested", "approved", "declined", "received", "closed"]}, "reason": {"type": "string"}, "reason_label": {"type": "string"}, "customer_note": {"type": "string", "nullable": true}, "seller_message": {"type": "string", "nullable": true}, "resolution": {"type": "string", "nullable": true, "enum": ["refund", "exchange", "none", null]}, "customer": {"type": "object", "properties": {"name": {"type": "string", "nullable": true}, "email": {"type": "string", "nullable": true}}}, "currency": {"type": "string"}, "value_amount": {"type": "integer"}, "items": {"type": "array", "items": {"type": "object", "properties": {"item_id": {"type": "integer"}, "variant_uuid": {"type": "string", "format": "uuid", "nullable": true}, "product_name": {"type": "string"}, "variant_title": {"type": "string"}, "sku": {"type": "string", "nullable": true}, "unit_amount": {"type": "integer"}, "quantity": {"type": "integer"}, "received_quantity": {"type": "integer", "nullable": true}, "restocked_quantity": {"type": "integer"}}}}, "refund_uuid": {"type": "string", "format": "uuid", "nullable": true}, "exchange_order_uuid": {"type": "string", "format": "uuid", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}, "decided_at": {"type": "string", "format": "date-time", "nullable": true}, "received_at": {"type": "string", "format": "date-time", "nullable": true}, "closed_at": {"type": "string", "format": "date-time", "nullable": true}, "updated_at": {"type": "string", "format": "date-time", "nullable": true}}, "required": ["uuid", "number", "order", "status", "items"]}, "StoreApiWebhook": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "url": {"type": "string", "format": "uri"}, "events": {"type": "array", "items": {"type": "string", "enum": ["store.order.paid", "store.order.fulfilled", "store.order.refunded", "store.order.canceled", "store.product.updated", "store.stock.low", "store.return.requested", "store.order.ready_for_pickup"]}}, "is_active": {"type": "boolean"}, "secret_last4": {"type": "string", "nullable": true}, "secret": {"type": "string", "description": "The whole signing secret: only in the response that creates the endpoint or rotates its secret."}, "last_delivered_at": {"type": "string", "format": "date-time", "nullable": true}, "last_failed_at": {"type": "string", "format": "date-time", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}}, "required": ["uuid", "name", "url", "events", "is_active"]}, "StoreApiWebhookDelivery": {"type": "object", "properties": {"id": {"type": "integer"}, "event_id": {"type": "string", "format": "uuid"}, "event_type": {"type": "string", "enum": ["store.order.paid", "store.order.fulfilled", "store.order.refunded", "store.order.canceled", "store.product.updated", "store.stock.low", "store.return.requested", "store.order.ready_for_pickup"]}, "subject": {"type": "string", "description": "What the event is about, such as order:."}, "status": {"type": "string", "enum": ["pending", "delivered", "failed", "canceled"]}, "attempts": {"type": "integer"}, "last_status": {"type": "integer", "nullable": true}, "last_failure": {"type": "string", "nullable": true, "enum": ["http_error", "network_error", "unsafe_destination", "missing_secret", null]}, "next_attempt_at": {"type": "string", "format": "date-time", "nullable": true}, "last_attempt_at": {"type": "string", "format": "date-time", "nullable": true}, "delivered_at": {"type": "string", "format": "date-time", "nullable": true}, "failed_at": {"type": "string", "format": "date-time", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}}, "required": ["id", "event_id", "event_type", "status", "attempts"]}, "StoreWebhookEvent": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid", "description": "The event id, also sent as X-Magpie-Id. The same on every retry and for every endpoint."}, "type": {"type": "string", "enum": ["store.order.paid", "store.order.fulfilled", "store.order.refunded", "store.order.canceled", "store.product.updated", "store.stock.low", "store.return.requested", "store.order.ready_for_pickup"]}, "created_at": {"type": "string", "format": "date-time"}, "data": {"type": "object", "properties": {"team": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}}}, "store": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "slug": {"type": "string"}, "currency": {"type": "string"}}}, "order": {"allOf": [{"$ref": "#/components/schemas/StoreApiOrderDetail"}], "description": "Order events, and the order a return belongs to (as listed)."}, "fulfillment": {"$ref": "#/components/schemas/StoreApiShipment"}, "refund": {"$ref": "#/components/schemas/StoreApiRefund"}, "product": {"description": "store.product.updated: the Product. store.stock.low: its uuid and title.", "allOf": [{"$ref": "#/components/schemas/StoreApiProduct"}]}, "variant": {"$ref": "#/components/schemas/StoreApiVariant"}, "return": {"$ref": "#/components/schemas/StoreApiReturn"}}, "required": ["team", "store"]}}, "required": ["id", "type", "created_at", "data"], "description": "The JSON body POSTed to a Store webhook endpoint. Headers: X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp and X-Magpie-Signature (t=,v1=.\" with the endpoint's secret). Answer with any 2xx status; other answers are retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours, then the delivery is failed."}, "CourseApiCourse": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "state": {"type": "string", "enum": ["draft", "published", "archived"]}, "slug": {"type": "string"}, "url": {"type": "string", "format": "uri", "nullable": true, "description": "The course's page at its school; null unless the course is published."}}, "required": ["uuid", "title", "state", "slug", "url"]}, "CourseApiCourseDetail": {"allOf": [{"$ref": "#/components/schemas/CourseApiCourse"}, {"type": "object", "properties": {"subtitle": {"type": "string", "nullable": true}, "mode": {"type": "string", "enum": ["self_paced", "cohort"]}, "join_mode": {"type": "string", "enum": ["free", "free_approval", "paid", "paid_approval", "invitation"]}, "students_with_access": {"type": "integer"}, "cohorts": {"type": "array", "description": "A cohort course's cohorts; empty for a self-paced course.", "items": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "starts_on": {"type": "string", "format": "date"}, "ends_on": {"type": "string", "format": "date", "nullable": true}, "state": {"type": "string", "enum": ["draft", "published", "cancelled"]}, "seats": {"type": "integer", "nullable": true}, "seats_left": {"type": "integer", "nullable": true, "description": "Null without a seat limit, and for a cancelled cohort."}}}}}}]}, "CourseApiEnrolment": {"type": "object", "description": "A student's enrolment in a course (CourseApiSerializer). Times are UTC.", "properties": {"uuid": {"type": "string", "format": "uuid"}, "student": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string", "description": "\"Deleted user\" for an erased student or a deleted account."}, "email": {"type": "string", "nullable": true}}, "required": ["uuid", "name", "email"]}, "state": {"type": "string", "enum": ["active", "waiting", "completed", "ended", "declined"], "description": "waiting: applied, or approved and not yet bought. completed: completed the course, with or without access now."}, "joined_via": {"type": "string", "enum": ["free", "order", "payment_plan", "supporters", "added", "import", "api"]}, "progress_percent": {"type": "integer", "minimum": 0, "maximum": 100}, "cohort": {"type": "object", "nullable": true, "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}}}, "access_state": {"type": "string", "enum": ["current", "paused", "held", "not_started", "ended", "none"], "description": "paused: a payment plan is behind. held: until the student confirms their email address."}, "access_ends_at": {"type": "string", "format": "date-time", "nullable": true, "description": "When current access ends (null for no end), or when it ended."}, "email_confirmed": {"type": "boolean", "nullable": true}, "enrolled_at": {"type": "string", "format": "date-time", "nullable": true}, "last_active_at": {"type": "string", "format": "date-time", "nullable": true}, "completed_at": {"type": "string", "format": "date-time", "nullable": true}}, "required": ["uuid", "student", "state", "joined_via", "progress_percent", "cohort", "access_state", "access_ends_at"]}, "CourseWebhookEvent": {"type": "object", "description": "The data of course.enrolled, course.completed and course.access_ended, sent once each to the webhooks of the owner of the course's team.", "properties": {"course": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "title": {"type": "string"}, "url": {"type": "string", "format": "uri", "nullable": true}}}, "enrolment": {"$ref": "#/components/schemas/CourseApiEnrolment"}, "student": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string", "description": "\"Deleted user\" for an erased student or a deleted account."}, "email": {"type": "string", "nullable": true}}, "required": ["uuid", "name", "email"]}, "event": {"type": "object", "properties": {"reason": {"type": "string", "nullable": true, "enum": ["refunded", "removed", "plan_canceled", "supporter_ended", "erased", null], "description": "course.access_ended: why the access ended; null when it ran out."}}}, "occurred_at": {"type": "string", "format": "date-time"}}, "required": ["course", "enrolment", "student", "event", "occurred_at"]}, "AssetTrackerAsset": {"type": "object","properties": {"name": {"type": "string","nullable": true},"assetTag": {"type": "string","nullable": true},"serialNumber": {"type": "string","nullable": true},"categoryName": {"type": "string","nullable": true},"manufacturer": {"type": "string","nullable": true},"model": {"type": "string","nullable": true},"description": {"type": "string","nullable": true},"status": {"type": "string","nullable": true},"effectiveStatus": {"type": "string","nullable": true},"condition": {"type": "string","nullable": true},"location": {"type": "string","nullable": true},"notes": {"type": "string","nullable": true},"tags": {"type": "string","nullable": true},"assignedUserName": {"type": "string","nullable": true},"assignedContactName": {"type": "string","nullable": true},"checkoutUserName": {"type": "string","nullable": true},"checkoutContactName": {"type": "string","nullable": true},"checkedOutAt": {"type": "string","nullable": true},"dueAt": {"type": "string","nullable": true},"checkoutCondition": {"type": "string","nullable": true},"checkoutNotes": {"type": "string","nullable": true},"purchaseDate": {"type": "string","nullable": true},"purchasePrice": {"type": "string","nullable": true},"purchaseCurrency": {"type": "string","nullable": true},"supplierName": {"type": "string","nullable": true},"supplierContactId": {"type": "integer","nullable": true},"supplierContactName": {"type": "string","nullable": true},"supplierContactUuid": {"type": "string","nullable": true},"warrantyExpiresAt": {"type": "string","nullable": true},"categoryId": {"type": "integer","nullable": true},"assignedUserId": {"type": "integer","nullable": true},"assignedContactId": {"type": "integer","nullable": true},"checkoutId": {"type": "integer","nullable": true},"checkedOutToUserId": {"type": "integer","nullable": true},"checkedOutToContactId": {"type": "integer","nullable": true},"overdue": {"type": "boolean"},"duplicateSerial": {"type": "boolean"},"bookingResourceActive": {"type": "boolean"},"can_edit": {"type": "boolean"},"can_checkout": {"type": "boolean"},"can_checkin": {"type": "boolean"},"is_admin": {"type": "boolean"},"uuid": {"type": "string","format": "uuid"},"primaryImageUuid": {"type": "string","format": "uuid","nullable": true},"bookingResourceUuid": {"type": "string","format": "uuid","nullable": true}},"required": ["uuid","name","can_edit","can_checkout","can_checkin","is_admin"],"description": "Asset identity and possession. Financial fields are present only for team admins. Storage paths are never returned."}, "AssetTrackerDetail": {"allOf": [{"$ref": "#/components/schemas/AssetTrackerAsset"},{"type": "object","properties": {"attachments": {"type": "array","items": {"type": "object","properties": {"uuid": {"type": "string","format": "uuid"},"originalFilename": {"type": "string"},"mimeType": {"type": "string"},"fileSize": {"type": "integer"},"isPrimaryImage": {"type": "boolean"}}}},"history": {"type": "array","items": {"type": "object"}},"maintenance": {"type": "array","items": {"type": "object"}}}}]}, "AssetTrackerCategory": {"type": "object","properties": {"id": {"type": "integer"},"uuid": {"type": "string","format": "uuid"},"name": {"type": "string"},"active": {"type": "boolean"}}}, "AssetTrackerOptions": {"type": "object","properties": {"can_edit": {"type": "boolean"},"is_admin": {"type": "boolean"},"actor_id": {"type": "integer"},"categories": {"type": "array","items": {"$ref": "#/components/schemas/AssetTrackerCategory"}},"conditions": {"type": "object","additionalProperties": {"type": "string"}},"statuses": {"type": "object","additionalProperties": {"type": "string"}},"members": {"type": "array","items": {"type": "object","properties": {"id": {"type": "integer"},"name": {"type": "string"},"email": {"type": "string"}}}},"contacts": {"type": "array","items": {"type": "object","properties": {"id": {"type": "integer"},"uuid": {"type": "string","format": "uuid"},"displayName": {"type": "string"}}}},"locations": {"type": "array","items": {"type": "string"}}}}, "MobileBook": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "author_name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "visibility": { "type": "string", "enum": [ "private", "public" ] }, "section_count": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time" }, "web_path": { "type": "string" }, "public_url": { "type": "string" }, "read_url": { "type": "string" } }, "required": [ "id", "title", "subtitle", "author_name", "status", "visibility", "section_count", "updated_at", "web_path", "public_url", "read_url" ] }, "MobileBookDetail": { "allOf": [ { "$ref": "#/components/schemas/MobileBook" }, { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "language_code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "description", "language_code", "created_at", "published_at" ] } ] }, "MobileBookSection": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "synopsis": { "type": "string", "nullable": true }, "status": { "type": "string" }, "is_included": { "type": "boolean" }, "matter": { "type": "string", "enum": [ "front", "body", "back" ] }, "is_part_break": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0 }, "word_count": { "type": "integer", "minimum": 0 }, "chapter_number": { "type": "integer", "minimum": 1, "nullable": true }, "part_label": { "type": "string" }, "source_date_label": { "type": "string", "nullable": true }, "excerpt": { "type": "string", "maxLength": 180 }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "synopsis", "status", "is_included", "matter", "is_part_break", "sort_order", "word_count", "chapter_number", "part_label", "source_date_label", "excerpt", "updated_at" ] }, "MobileBookSectionDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "book_id": { "type": "integer" }, "title": { "type": "string" }, "is_part_break": { "type": "boolean" }, "is_included": { "type": "boolean" }, "matter": { "type": "string", "enum": [ "front", "body", "back" ] }, "word_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "revision": { "type": "string" }, "can_edit_text": { "type": "boolean" }, "markdown": { "type": "string", "nullable": true }, "pictures": { "type": "array", "items": { "type": "string" }, "description": "Caption or description for each [[Picture N]] placeholder" }, "plain_text": { "type": "string" } }, "required": [ "id", "book_id", "title", "is_part_break", "is_included", "matter", "word_count", "updated_at", "revision", "can_edit_text", "markdown", "pictures", "plain_text" ] }, "MobileBookContents": { "type": "object", "properties": { "groups": { "type": "object", "properties": { "front": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBookSection" } }, "body": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBookSection" } }, "back": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBookSection" } }, "set_aside": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBookSection" } } }, "required": [ "front", "body", "back", "set_aside" ] }, "truncated": { "type": "boolean" }, "arrangement": { "type": "string", "description": "Changes whenever a section moves; send it as base_arrangement when moving a section" } }, "required": [ "groups", "truncated", "arrangement" ] }, "Booking": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "attendee": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "sms_opt_in": { "type": "boolean" }, "sms_reminder_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "confirmed", "cancelled", "completed" ] }, "host_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "zoom": { "type": "object", "properties": { "meeting_id": { "type": "string", "nullable": true }, "join_url": { "type": "string", "nullable": true }, "start_url": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true } } }, "google": { "type": "object", "properties": { "calendar_event_id": { "type": "string", "nullable": true }, "meet_link": { "type": "string", "nullable": true } } } } }, "EventType": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Availability": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user_id": { "type": "integer" }, "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "start_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_confirmed": { "type": "boolean", "description": "False while the account's address waits for confirmation; the app shows Confirm your email address." }, "slug": { "type": "string" }, "timezone": { "type": "string" }, "theme_preference": { "type": "string", "enum": [ "system", "light", "dark" ] }, "is_admin": { "type": "boolean" } } }, "MobileProfile": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "minLength": 2, "maxLength": 255 }, "email": { "type": "string", "format": "email", "nullable": true }, "slug": { "type": "string" }, "username": { "type": "string", "nullable": true }, "bio": { "type": "string", "maxLength": 1000, "nullable": true }, "avatar_image_uuid": { "type": "string", "format": "uuid", "nullable": true }, "timezone": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "IssueComment": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "author_name": { "type": "string" }, "body_markdown": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": ["uuid", "author_name", "body_markdown", "created_at", "updated_at"] }, "Issue": { "type": "object", "required": ["uuid", "identifier", "title", "status", "priority", "updated_at"], "properties": { "uuid": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "description": "A status key configured in the selected team." }, "priority": { "type": "string", "enum": ["none", "urgent", "high", "medium", "low"] }, "creator_name": { "type": "string" }, "assignee_user_id": { "type": "integer", "nullable": true }, "assignee_name": { "type": "string", "nullable": true }, "project": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } } }, "milestone": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } } }, "cycle": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "integer", "nullable": true } } }, "updated_at": { "type": "string", "format": "date-time" }, "description_markdown": { "type": "string" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "triage": { "type": "object", "nullable": true, "properties": { "state": { "type": "string" }, "source": { "type": "string" } } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret_last4": { "type": "string", "nullable": true }, "secret": { "type": "string", "description": "Only returned when creating or rotating secret" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Tool": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "blurb": { "type": "string" }, "web_path": { "type": "string" }, "can_create": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "account", "tool" ] }, "group": { "type": "string", "description": "Canonical homepage product group key." }, "group_label": { "type": "string", "description": "Canonical homepage product group label." }, "group_order": { "type": "integer", "minimum": 0, "description": "Canonical homepage product group order." } } }, "MobileIntegrationStatus": { "type": "object", "description": "Safe account-owned provider status. Credentials, settings and provider endpoints are never returned.", "properties": { "key": { "type": "string", "enum": [ "google_calendar", "slack", "zoom", "twilio" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "reauthorization_required", "not_connected", "configured", "not_configured" ] }, "scope": { "type": "string", "enum": [ "account" ] }, "web_path": { "type": "string", "enum": [ "/integrations" ] }, "last_updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "key", "name", "description", "status", "scope", "web_path", "last_updated_at" ] }, "MobileNotificationPreferences": { "type": "object", "description": "Bounded account-owned Slack meeting notification settings. Credentials and raw provider settings are never returned.", "properties": { "channels": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "slack", "push" ] }, "name": { "type": "string" }, "available": { "type": "boolean" }, "status": { "type": "string", "enum": [ "connected", "not_connected", "unavailable", "registered", "not_registered" ] }, "web_path": { "type": "string", "nullable": true }, "registered": { "type": "integer", "minimum": 0 }, "platforms": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "available", "status", "web_path" ] } }, "slack": { "type": "object", "properties": { "connected": { "type": "boolean" }, "channel_options": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileNotificationOption" } }, "member_options": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileNotificationOption" } }, "selected_channel_id": { "type": "string", "nullable": true }, "selected_dm_user_id": { "type": "string", "nullable": true }, "preferences": { "$ref": "#/components/schemas/MobileSlackNotificationPreferences" }, "web_path": { "type": "string", "enum": [ "/integrations" ] } }, "required": [ "connected", "channel_options", "member_options", "selected_channel_id", "selected_dm_user_id", "preferences", "web_path" ] } }, "required": [ "channels", "slack" ] }, "MobileNotificationOption": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "MobilePushTokenStatus": { "type": "object", "properties": { "registered": { "type": "integer", "minimum": 0 }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "ios", "android" ] } } }, "required": [ "registered", "platforms" ] }, "MobileSlackNotificationPreferences": { "type": "object", "properties": { "notify_new_booking": { "type": "boolean" }, "notify_confirmed": { "type": "boolean" }, "notify_cancelled": { "type": "boolean" }, "notify_rescheduled": { "type": "boolean" }, "notify_zoom_added": { "type": "boolean" } }, "required": [ "notify_new_booking", "notify_confirmed", "notify_cancelled", "notify_rescheduled", "notify_zoom_added" ] }, "MobileContact": { "type": "object", "properties": { "uuid": { "type": "string" }, "prefix": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "middleName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "suffix": { "type": "string", "nullable": true }, "displayName": { "type": "string" }, "companyName": { "type": "string", "nullable": true }, "avatar_image_uuid": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true }, "can_edit": { "type": "boolean" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "label": { "type": "string", "nullable": true } } } }, "phones": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "label": { "type": "string", "nullable": true } } } } } }, "MobileInvoiceLineItem": { "type": "object", "properties": { "uuid": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "line_total": { "type": "number" }, "quantity_text": { "type": "string", "description": "The quantity without trailing zeros, up to four decimal places." }, "unit_price_minor": { "type": "integer" }, "line_total_minor": { "type": "integer" }, "tax_rate_uuid": { "type": "string", "format": "uuid", "nullable": true }, "tax_rate_name": { "type": "string", "nullable": true, "description": "The tax rate's label when the line was saved." } } }, "MobileInvoice": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "due", "overdue", "paid", "void" ] }, "document_state": { "type": "string", "enum": [ "draft", "issued", "void" ] }, "payment_status": { "type": "string", "enum": [ "unpaid", "partial", "paid" ] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "currency": { "type": "string" }, "tax_rate_percent": { "type": "number" }, "discount_amount": { "type": "number" }, "discount_is_percent": { "type": "boolean" }, "subtotal": { "type": "number" }, "tax_amount": { "type": "number" }, "total": { "type": "number" }, "notes": { "type": "string", "nullable": true }, "terms": { "type": "string", "nullable": true }, "seller_name": { "type": "string", "nullable": true }, "seller_address": { "type": "string", "nullable": true }, "seller_tax_id": { "type": "string", "nullable": true }, "customer_name": { "type": "string" }, "customer_company": { "type": "string", "nullable": true }, "customer_billing_address": { "type": "string", "nullable": true }, "contact_uuid": { "type": "string", "format": "uuid", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_overdue": { "type": "integer" }, "issued_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "voided_at": { "type": "string", "format": "date-time", "nullable": true }, "line_items": { "type": "array", "nullable": true, "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileInvoiceLineItem" } }, "line_items_truncated": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "total_minor": { "type": "integer", "description": "Invoice total in integer minor units." }, "amount_paid_minor": { "type": "integer", "description": "Payments less refunds, in integer minor units." }, "balance_due_minor": { "type": "integer" }, "amount_paid": { "type": "number" }, "balance_due": { "type": "number" }, "can_record_payment": { "type": "boolean" }, "can_record_refund": { "type": "boolean" }, "payments": { "type": "array", "nullable": true, "description": "Present on invoice detail responses; null in lists.", "items": { "$ref": "#/components/schemas/MobileInvoicePayment" } }, "subtotal_minor": { "type": "integer" }, "discount_minor": { "type": "integer" }, "tax_minor": { "type": "integer" }, "pay_path": { "type": "string", "nullable": true, "description": "The customer's signed card-payment page, relative to the site, when card payment is offered now. Detail responses only." }, "overpaid_minor": { "type": "integer", "description": "Amount paid online beyond the total, in minor units." }, "taxes": { "type": "array", "description": "One entry per tax component charged, such as GST 5%.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "rate_percent": { "type": "string" }, "label": { "type": "string" }, "taxable_minor": { "type": "integer" }, "amount_minor": { "type": "integer" }, "amount": { "type": "number" } } } } } }, "MobileInvoicePayment": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": ["payment", "refund"] }, "amount": { "type": "number" }, "amount_minor": { "type": "integer" }, "currency": { "type": "string" }, "received_on": { "type": "string", "format": "date" }, "method": { "type": "string", "enum": ["bank_transfer", "card", "cash", "cheque", "online", "other"] }, "method_label": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "recorded_by": { "type": "string", "nullable": true } } }, "MobileInvoiceEditorContact": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "company_name": { "type": "string", "nullable": true }, "default_payment_terms_days": { "type": "integer", "nullable": true } }, "required": [ "uuid", "display_name", "company_name", "default_payment_terms_days" ] }, "MobileInvoiceOptions": { "type": "object", "properties": { "contacts": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileInvoiceEditorContact" } }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "defaults": { "type": "object", "properties": { "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "tax_rate_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "The tax rate new items start with." }, "tax_rate_percent": { "type": "number", "description": "For app builds that predate tax rates: the default rate's percentage when it has one component, otherwise 0." }, "terms": { "type": "string" } }, "required": [ "issue_date", "due_date", "currency", "tax_rate_uuid", "terms" ] }, "tax_rates": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } } }, "required": [ "contacts", "currencies", "defaults", "tax_rates" ] }, "MobileTaxRate": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "label": { "type": "string", "description": "\"HST 13%\", or \"GST + PST (GST 5%, PST 7%)\" for a combined rate." }, "applies_by_default": { "type": "boolean" }, "active": { "type": "boolean" }, "components": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate_percent": { "type": "string" }, "is_compound": { "type": "boolean" }, "is_recoverable": { "type": "boolean" } } } } } }, "MobileInvoiceSettings": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "numbering": { "type": "object", "properties": { "number_prefix": { "type": "string" }, "next_number": { "type": "integer" }, "number_padding": { "type": "integer" }, "formatted_next_number": { "type": "string" } }, "required": [ "number_prefix", "next_number", "number_padding", "formatted_next_number" ] }, "defaults": { "type": "object", "properties": { "currency": { "type": "string" }, "default_tax_rate": { "type": "string", "nullable": true, "description": "The label of the tax rate new items start with." }, "tax_rate_percent": { "type": "number", "description": "For app builds that predate tax rates." }, "payment_terms_days": { "type": "integer" }, "footer_notes": { "type": "string", "nullable": true } }, "required": [ "currency", "default_tax_rate", "payment_terms_days", "footer_notes" ] }, "business": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "tax_id": { "type": "string", "nullable": true }, "logo_present": { "type": "boolean" } }, "required": [ "name", "address", "tax_id", "logo_present" ] }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "uuid", "numbering", "defaults", "business", "currencies" ] }, "MobileInvoiceSettingsWrite": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "numbering", "defaults", "business" ] }, "number_prefix": { "type": "string", "maxLength": 20 }, "next_number": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "number_padding": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "currency": { "type": "string" }, "tax_rate_percent": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "payment_terms_days": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "footer_notes": { "type": "string", "maxLength": 5000 }, "name": { "type": "string", "nullable": true, "maxLength": 255 }, "address": { "type": "string", "nullable": true, "maxLength": 5000 }, "tax_id": { "type": "string", "nullable": true, "maxLength": 100 } }, "required": [ "section" ] }, "MobileInvoiceLogoWrite": { "type": "object", "additionalProperties": false, "properties": { "image_uuid": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "image_uuid" ] }, "MobileInvoiceWrite": { "type": "object", "properties": { "contact_uuid": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "tax_rate_percent": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "discount_amount": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "discount_is_percent": { "type": "boolean" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "items": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "unit_price": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "tax_rate_uuid": { "type": "string", "description": "One of the team's tax rates, or empty for no tax." } }, "required": [ "description", "quantity", "unit_price" ] } } }, "required": [ "contact_uuid", "currency", "issue_date", "due_date", "discount_amount", "discount_is_percent", "notes", "terms", "items" ] }, "MobileInvoiceSendOptions": { "type": "object", "properties": { "emails": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "label": { "type": "string", "nullable": true }, "is_primary": { "type": "boolean" } }, "required": [ "email", "label", "is_primary" ] } } }, "required": [ "emails" ] }, "MobileInvoiceSendResult": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" }, "sent_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "already_processed": { "type": "boolean" } }, "required": [ "data", "sent_count", "failed_count", "already_processed" ] }, "MobileStoreOverview": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active" ] }, "currency": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ready": { "type": "boolean" }, "active_product_count": { "type": "integer" }, "ready_product_count": { "type": "integer" }, "active_shipping_method_count": { "type": "integer" }, "payments_ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "object" } }, "web_path": { "type": "string" } }, "required": [ "uuid", "name", "slug", "status", "currency", "ready", "active_product_count", "ready_product_count", "active_shipping_method_count", "payments_ready", "missing", "web_path" ] }, "MobileStorePayments": { "type": "object", "properties": { "configured": { "type": "boolean" }, "status": { "type": "string", "enum": [ "not_started", "incomplete", "restricted", "ready" ] }, "status_label": { "type": "string" }, "charges_enabled": { "type": "boolean" }, "payouts_enabled": { "type": "boolean" }, "details_submitted": { "type": "boolean" }, "currently_due_count": { "type": "integer", "minimum": 0 }, "country": { "type": "string", "nullable": true }, "default_currency": { "type": "string", "nullable": true }, "countries": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "web_path": { "type": "string" } }, "required": [ "configured", "status", "status_label", "charges_enabled", "payouts_enabled", "details_submitted", "currently_due_count", "country", "default_currency", "countries", "web_path" ] }, "MobileStoreShippingMethod": { "type": "object", "properties": { "method_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "flat", "free", "free_over" ] }, "amount": { "type": "integer" }, "threshold_amount": { "type": "integer", "nullable": true }, "delivery_description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } }, "required": [ "method_id", "name", "type", "amount", "threshold_amount", "delivery_description", "is_active" ] }, "MobileStoreShippingZone": { "type": "object", "properties": { "zone_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "methods": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileStoreShippingMethod" } } }, "required": [ "zone_id", "name", "countries", "is_active", "methods" ] }, "MobileStoreShippingData": { "type": "object", "properties": { "currency": { "type": "string" }, "zones": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileStoreShippingZone" } } }, "required": [ "currency", "zones" ] }, "MobileStoreSettings": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "origin_country": { "type": "string", "nullable": true }, "shipping_policy": { "type": "string", "nullable": true }, "returns_policy": { "type": "string", "nullable": true }, "slug_locked": { "type": "boolean" }, "currency_locked": { "type": "boolean" }, "web_path": { "type": "string" } }, "required": [ "name", "slug", "description", "contact_email", "currency", "currencies", "origin_country", "shipping_policy", "returns_policy", "slug_locked", "currency_locked", "web_path" ] }, "MobileStoreCollection": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "active" ] }, "product_count": { "type": "integer", "minimum": 0 }, "web_path": { "type": "string" } }, "required": [ "uuid", "title", "slug", "description", "status", "product_count", "web_path" ] }, "MobileStoreCollectionsData": { "type": "object", "properties": { "collections": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileStoreCollection" } }, "products": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileStoreProduct" } } }, "required": [ "collections", "products" ] }, "MobileStoreCollectionDetail": { "allOf": [ { "$ref": "#/components/schemas/MobileStoreCollection" }, { "type": "object", "properties": { "selected_product_uuids": { "type": "array", "maxItems": 200, "items": { "type": "string", "format": "uuid" } }, "products": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileStoreProduct" } } }, "required": [ "selected_product_uuids", "products" ] } ] }, "MobileStoreDigitalFile": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "filesize": { "type": "integer", "minimum": 0 }, "mimetype": { "type": "string" }, "display_size": { "type": "string" }, "format_label": { "type": "string" }, "created_at": { "type": "string", "nullable": true } }, "required": [ "uuid", "filename", "filesize", "mimetype", "display_size", "format_label" ] }, "MobileStoreDigitalFilePage": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileStoreDigitalFile" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] }, "MobileStoreProduct": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "requires_shipping": { "type": "boolean" }, "is_featured": { "type": "boolean" }, "price_amount": { "type": "integer", "nullable": true }, "max_price_amount": { "type": "integer", "nullable": true }, "currency": { "type": "string" }, "active_variant_count": { "type": "integer" }, "available_variant_count": { "type": "integer" }, "image_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "web_path": { "type": "string" } }, "required": [ "uuid", "title", "slug", "status", "requires_shipping", "is_featured", "price_amount", "max_price_amount", "currency", "active_variant_count", "available_variant_count", "image_count", "updated_at", "web_path" ] }, "MobileStoreProductVariant": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "price_amount": { "type": "integer" }, "compare_at_amount": { "type": "integer", "nullable": true }, "unit_cost_amount": { "type": "integer", "nullable": true, "description": "Weighted-average cost per item in the Store currency's minor units." }, "sku": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "track_inventory": { "type": "boolean" }, "inventory_quantity": { "type": "integer" }, "reserved_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" } }, "required": [ "uuid", "title", "price_amount", "compare_at_amount", "sku", "is_active", "track_inventory", "inventory_quantity", "reserved_quantity", "available_quantity" ] }, "MobileStoreProductImage": { "type": "object", "properties": { "image_id": { "type": "integer", "minimum": 1 }, "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "alt_text": { "type": "string" }, "position": { "type": "integer", "minimum": 0 } }, "required": [ "image_id", "uuid", "filename", "alt_text", "position" ] }, "MobileStoreProductOption": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "values": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 100 } } }, "required": [ "name", "values" ] }, "MobileStoreProductDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "product_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "requires_shipping": { "type": "boolean" }, "is_featured": { "type": "boolean" }, "currency": { "type": "string" }, "image_count": { "type": "integer" }, "images": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileStoreProductImage" } }, "images_truncated": { "type": "boolean" }, "published_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "digital_file": { "allOf": [ { "$ref": "#/components/schemas/MobileStoreDigitalFile" } ], "nullable": true }, "options": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/MobileStoreProductOption" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/MobileStoreProductVariant" } }, "web_path": { "type": "string" } }, "required": [ "uuid", "title", "slug", "description", "product_type", "status", "requires_shipping", "is_featured", "currency", "image_count", "images", "images_truncated", "published_at", "updated_at", "digital_file", "options", "variants", "web_path" ] }, "MobileStoreOrderItem": { "type": "object", "properties": { "product_name": { "type": "string" }, "variant_title": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "unit_amount": { "type": "integer" }, "quantity": { "type": "integer" }, "line_total_amount": { "type": "integer" } }, "required": [ "product_name", "variant_title", "sku", "unit_amount", "quantity", "line_total_amount" ] }, "MobileStoreOrder": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string" }, "customer_name": { "type": "string" }, "payment_state": { "type": "string" }, "fulfillment_state": { "type": "string" }, "currency": { "type": "string" }, "total_amount": { "type": "integer" }, "item_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "web_path": { "type": "string" }, "subtotal_amount": { "type": "integer" }, "shipping_amount": { "type": "integer" }, "tax_amount": { "type": "integer" }, "items": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileStoreOrderItem" } }, "items_truncated": { "type": "boolean" }, "fulfillment": { "type": "object", "nullable": true } }, "required": [ "uuid", "order_number", "customer_name", "payment_state", "fulfillment_state", "currency", "total_amount", "item_count", "created_at", "web_path" ] }, "MobileTodo": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "notesMarkdown": { "type": "string", "nullable": true }, "whenDate": { "type": "string", "nullable": true }, "whenTime": { "type": "string", "nullable": true }, "deadlineDate": { "type": "string", "nullable": true }, "priority": { "type": "string" }, "completed": { "type": "boolean" }, "can_edit": { "type": "boolean" } } }, "MobileAgendaItem": { "type": "object", "properties": { "uuid": { "type": "string" }, "kind": { "type": "string", "enum": [ "event", "meeting", "todo" ] }, "title": { "type": "string" }, "startAt": { "type": "string" }, "endAt": { "type": "string" }, "allDay": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "manageUrl": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } }, "MobileAgenda": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MobileAgendaItem" } }, "meetings": { "type": "array", "items": { "$ref": "#/components/schemas/MobileAgendaItem" } }, "todos": { "type": "array", "items": { "$ref": "#/components/schemas/MobileAgendaItem" } } } }, "MobileImage": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mimetype": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "displaySize": { "type": "string" } }, "required": [ "uuid", "filename", "mimetype", "width", "height", "displaySize" ] }, "MobileFaviconProject": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "image_uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "download_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "last_generated_at": { "type": "string", "format": "date-time", "nullable": true }, "download_path": { "type": "string" } }, "required": [ "uuid", "name", "image_uuid", "filename", "width", "height", "download_count", "created_at", "last_generated_at", "download_path" ] }, "MobileBoard": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "team_name": { "type": "string" }, "post_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_public": { "type": "boolean" }, "can_post": { "type": "boolean" }, "can_manage": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "archived_at": { "type": "string", "nullable": true, "description": "When the board was archived. An archived board can be read but takes no posts, comments or votes, and can_post is false." }, "comment_count": { "type": "integer", "nullable": true, "description": "Comments on the board's shown posts, for the Delete board confirmation. Set only where the board is read on its own (GET, PATCH, archive and restore of /boards/{slug}) by its creator or a team admin while it is archived; null otherwise." }, "web_path": { "type": "string" } }, "required": [ "slug", "name", "description", "visibility", "team_name", "post_count", "is_member", "is_public", "can_post", "can_manage", "created_at", "updated_at", "archived_at", "comment_count", "web_path" ] }, "MobilePresentationTemplate": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "key", "label", "description" ] }, "MobilePresentationCollaborator": { "type": "object", "properties": { "user_id": { "type": "integer", "minimum": 1 }, "username": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "view", "edit" ] } }, "required": [ "user_id", "username", "name", "access" ] }, "MobileDesignVersion": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "maxLength": 150 }, "reason": { "type": "string", "description": "checkpoint, named, restore, branch or merge" }, "revision": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_username": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "uuid", "name", "reason", "revision", "creator_name", "creator_username", "created_at" ] }, "MobileDesignVersionHistory": { "type": "object", "properties": { "versions": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileDesignVersion" } }, "revision": { "type": "integer", "description": "The Design's current Main revision" }, "can_create": { "type": "boolean" }, "can_restore": { "type": "boolean" } }, "required": [ "versions", "revision", "can_create", "can_restore" ] }, "MobileDesignBranch": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 150 }, "status": { "type": "string", "description": "active or merged" }, "base_revision": { "type": "integer" }, "revision": { "type": "integer" }, "behind_main": { "type": "boolean", "description": "An active Branch whose base is older than Main; it must be updated before it can be merged" }, "creator_name": { "type": "string" }, "created_at": { "type": "string" }, "merged_at": { "type": [ "string", "null" ] }, "web_path": { "type": "string", "description": "Same-origin Web editor address for the Branch" } }, "required": [ "uuid", "name", "status", "base_revision", "revision", "behind_main", "creator_name", "created_at", "merged_at", "web_path" ] }, "MobileDesignBranches": { "type": "object", "properties": { "branches": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileDesignBranch" } }, "revision": { "type": "integer", "description": "The Design's current Main revision" }, "can_create": { "type": "boolean" }, "can_update": { "type": "boolean" }, "can_merge": { "type": "boolean" } }, "required": [ "branches", "revision", "can_create", "can_update", "can_merge" ] }, "MobileDesignCollaborator": { "type": "object", "properties": { "user_id": { "type": "integer", "minimum": 1 }, "username": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "viewer", "commenter", "editor" ] } }, "required": [ "user_id", "username", "name", "access" ] }, "MobilePresentationOutline": { "type": "object", "properties": { "draft_version": { "type": "integer" }, "can_edit": { "type": "boolean" }, "slides": { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "maxLength": 150 }, "hidden": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 10000 }, "element_count": { "type": "integer" }, "texts": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string", "maxLength": 10000 } }, "required": [ "id", "text" ] } } }, "required": [ "id", "title", "hidden", "notes", "element_count", "texts" ] } } }, "required": [ "draft_version", "can_edit", "slides" ] }, "MobilePresentation": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 255 }, "template_key": { "type": "string" }, "creator_name": { "type": "string" }, "team_name": { "type": "string" }, "draft_version": { "type": "integer", "minimum": 0 }, "published_version": { "type": "integer", "minimum": 0, "nullable": true }, "share_state": { "type": "string", "enum": [ "private", "link" ] }, "slide_count": { "type": "integer", "minimum": 0, "maximum": 200 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "web_path": { "type": "string" }, "share_path": { "type": "string", "nullable": true, "description": "Public path only when a version is published and link sharing is on" }, "can_edit": { "type": "boolean" }, "can_duplicate": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "can_publish": { "type": "boolean" }, "can_share": { "type": "boolean" } }, "required": [ "uuid", "title", "template_key", "creator_name", "team_name", "draft_version", "published_version", "share_state", "slide_count", "created_at", "updated_at", "web_path", "share_path", "can_edit", "can_duplicate", "can_delete", "can_publish", "can_share" ] }, "MobileNewsletterPublication": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string", "maxLength": 150 }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "signup_enabled": { "type": "boolean" }, "archive_enabled": { "type": "boolean" }, "sender_name": { "type": "string", "nullable": true, "maxLength": 150 }, "reply_to_email": { "type": "string", "nullable": true, "format": "email" }, "footer_text": { "type": "string", "nullable": true, "maxLength": 1000 }, "public_path": { "type": "string" }, "active_subscribers": { "type": "integer", "minimum": 0 }, "pending_subscribers": { "type": "integer", "minimum": 0 }, "sent_count": { "type": "integer", "minimum": 0 }, "total_sent": { "type": "integer", "minimum": 0 }, "draft_count": { "type": "integer", "minimum": 0 }, "scheduled_count": { "type": "integer", "minimum": 0 }, "can_edit": { "type": "boolean" }, "can_admin": { "type": "boolean" } }, "required": [ "uuid", "slug", "title", "description", "status", "signup_enabled", "archive_enabled", "sender_name", "reply_to_email", "footer_text", "public_path", "active_subscribers", "pending_subscribers", "sent_count", "total_sent", "draft_count", "scheduled_count", "can_edit", "can_admin" ] }, "MobileNewsletterPost": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "maxLength": 255 }, "preview_text": { "type": "string", "nullable": true, "maxLength": 255 }, "content_markdown": { "type": "string", "nullable": true, "maxLength": 200000 }, "status": { "type": "string" }, "status_label": { "type": "string", "maxLength": 80 }, "is_open": { "type": "boolean" }, "is_editable": { "type": "boolean" }, "is_cancelable": { "type": "boolean" }, "was_sent": { "type": "boolean" }, "author_name": { "type": "string" }, "recipient_total": { "type": "integer", "minimum": 0 }, "sent_total": { "type": "integer", "minimum": 0 }, "failed_total": { "type": "integer", "minimum": 0 }, "skipped_total": { "type": "integer", "minimum": 0 }, "scheduled_for": { "type": "string", "nullable": true }, "sent_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "public_path": { "type": "string", "nullable": true }, "web_path": { "type": "string" } }, "required": [ "uuid", "subject", "preview_text", "content_markdown", "status", "status_label", "is_open", "is_editable", "is_cancelable", "was_sent", "author_name", "recipient_total", "sent_total", "failed_total", "skipped_total", "scheduled_for", "sent_at", "created_at", "updated_at", "public_path", "web_path" ] }, "MobileNewsletterOverview": { "type": "object", "properties": { "publication": { "$ref": "#/components/schemas/MobileNewsletterPublication", "nullable": true }, "posts": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "can_edit": { "type": "boolean" }, "can_admin": { "type": "boolean" } }, "required": [ "publication", "posts", "can_edit", "can_admin" ] }, "MobileNewsletterSubscriber": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "display_name": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "source_label": { "type": "string" }, "requested_at": { "type": "string" }, "confirmed_at": { "type": "string", "nullable": true } }, "required": [ "uuid", "email", "display_name", "status", "status_label", "source_label", "requested_at", "confirmed_at" ] }, "MobileNewsletterSubscriberPage": { "type": "object", "properties": { "subscribers": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/MobileNewsletterSubscriber" } }, "total": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" }, "filter": { "type": "string" }, "counts": { "type": "object", "properties": { "active": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "unsubscribed": { "type": "integer", "minimum": 0 }, "removed": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 } }, "required": [ "active", "pending", "unsubscribed", "removed", "suppressed" ] } }, "required": [ "subscribers", "total", "truncated", "filter", "counts" ] }, "MobileDesign": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 150 }, "creator_name": { "type": "string" }, "team_name": { "type": "string" }, "revision": { "type": "integer", "minimum": 0 }, "checkpoint_revision": { "type": "integer", "minimum": 0 }, "collaborator_count": { "type": "integer", "minimum": 0 }, "archived_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "web_path": { "type": "string" }, "can_edit": { "type": "boolean" }, "can_comment": { "type": "boolean" }, "can_manage": { "type": "boolean" }, "can_duplicate": { "type": "boolean" } }, "required": [ "uuid", "title", "creator_name", "team_name", "revision", "checkpoint_revision", "collaborator_count", "archived_at", "created_at", "updated_at", "web_path", "can_edit", "can_comment", "can_manage", "can_duplicate" ] }, "MobileDesignComment": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "body_markdown": { "type": "string", "maxLength": 10000 }, "author_name": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "page_id": { "type": "string", "nullable": true, "maxLength": 80 }, "layer_id": { "type": "string", "nullable": true, "maxLength": 80 }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "uuid", "body_markdown", "author_name", "status", "page_id", "layer_id", "parent_uuid", "created_at", "updated_at" ] }, "MobileDesignComments": { "type": "object", "properties": { "comments": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileDesignComment" } }, "can_comment": { "type": "boolean" } }, "required": [ "comments", "can_comment" ] }, "MobileBoardPost": { "type": "object", "properties": { "public_id": { "type": "string" }, "title": { "type": "string" }, "body_markdown": { "type": "string", "nullable": true, "maxLength": 5000 }, "link_url": { "type": "string", "nullable": true }, "author_name": { "type": "string" }, "score": { "type": "integer" }, "comment_count": { "type": "integer" }, "viewer_vote": { "type": "integer", "enum": [ -1, 0, 1 ] }, "locked": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "web_path": { "type": "string" } }, "required": [ "public_id", "title", "body_markdown", "link_url", "author_name", "score", "comment_count", "viewer_vote", "locked", "can_delete", "created_at", "updated_at", "web_path" ] }, "MobileBoardComment": { "type": "object", "properties": { "public_id": { "type": "string" }, "body_markdown": { "type": "string", "maxLength": 5000 }, "author_name": { "type": "string" }, "score": { "type": "integer" }, "viewer_vote": { "type": "integer", "enum": [ -1, 0, 1 ] }, "is_deleted": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBoardComment" } } }, "required": [ "public_id", "body_markdown", "author_name", "score", "viewer_vote", "is_deleted", "can_delete", "created_at", "children" ] }, "MobileBoardPage": { "type": "object", "properties": { "board": { "$ref": "#/components/schemas/MobileBoard" }, "sort": { "type": "string", "enum": [ "hot", "new", "top" ] }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBoardPost" } } }, "required": [ "board", "sort", "posts" ] }, "MobileBoardPostDetail": { "allOf": [ { "$ref": "#/components/schemas/MobileBoardPost" }, { "type": "object", "properties": { "board": { "$ref": "#/components/schemas/MobileBoard" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBoardComment" } } }, "required": [ "board", "comments" ] } ] }, "MobileReaderEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "author": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "feed_id": { "type": "integer" }, "feed_title": { "type": "string" }, "published_at": { "type": "string", "nullable": true }, "fetched_at": { "type": "string" }, "read_at": { "type": "string", "nullable": true } }, "required": [ "id", "title", "author", "content", "url", "feed_id", "feed_title", "published_at", "fetched_at", "read_at" ] }, "MobileReaderSubscription": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "source_type": { "type": "string" }, "site_url": { "type": "string", "nullable": true }, "unread_count": { "type": "integer" }, "item_count": { "type": "integer" }, "last_check_failed": { "type": "boolean", "description": "Whether the most recent fetch failed; raw stored errors are not returned" }, "last_checked_date": { "type": "string", "format": "date", "nullable": true }, "last_successful_date": { "type": "string", "format": "date", "nullable": true } }, "required": [ "id", "title", "source_type", "site_url", "unread_count", "item_count", "last_check_failed", "last_checked_date", "last_successful_date" ] }, "MobileReaderPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MobileReaderEntry" } }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/MobileReaderSubscription" } }, "filter": { "type": "string", "enum": [ "all", "unread" ] }, "feed_id": { "type": "integer", "nullable": true }, "page": { "type": "integer" }, "has_more": { "type": "boolean" }, "unread_count": { "type": "integer" }, "global_unread_count": { "type": "integer" }, "view_mode": { "type": "string", "enum": [ "preview", "compact", "expanded" ] } }, "required": [ "items", "subscriptions", "filter", "feed_id", "page", "has_more", "unread_count", "global_unread_count", "view_mode" ] }, "MobileVideoChatIceServer": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "username": { "type": "string", "nullable": true }, "credential": { "type": "string", "nullable": true } }, "required": [ "urls" ] }, "MobileVideoChatRoom": { "type": "object", "properties": { "code": { "type": "string", "minLength": 4, "maxLength": 4 }, "token": { "type": "string" }, "role": { "type": "string", "enum": [ "host", "guest" ] }, "durationMinutes": { "type": "integer" }, "startedAt": { "type": "integer", "nullable": true }, "endsAt": { "type": "integer", "nullable": true }, "serverNow": { "type": "integer" }, "iceServers": { "type": "array", "items": { "$ref": "#/components/schemas/MobileVideoChatIceServer" } } }, "required": [ "code", "token", "role", "durationMinutes", "startedAt", "endsAt", "serverNow", "iceServers" ] }, "MobileVideoChatSignal": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "offer", "answer", "ice", "hangup" ] }, "payload": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "id", "kind", "payload" ] }, "MobileVideoChatPoll": { "type": "object", "properties": { "signals": { "type": "array", "items": { "$ref": "#/components/schemas/MobileVideoChatSignal" } }, "cursor": { "type": "integer" }, "peerJoined": { "type": "boolean" }, "ended": { "type": "boolean" }, "durationMinutes": { "type": "integer" }, "startedAt": { "type": "integer", "nullable": true }, "endsAt": { "type": "integer", "nullable": true }, "serverNow": { "type": "integer" } }, "required": [ "signals", "cursor", "peerJoined", "ended", "durationMinutes", "startedAt", "endsAt", "serverNow" ] }, "MobileVaultCryptoRecord": { "type": "object", "properties": { "cryptoVersion": { "type": "integer" }, "kdfAlgorithm": { "type": "string" }, "kdfVersion": { "type": "integer" }, "kdfSalt": { "type": "string" }, "kdfOpsLimitName": { "type": "string" }, "kdfMemLimitName": { "type": "string" }, "wrappedUserVaultKey": { "type": "string" }, "wrappedUserVaultKeyNonce": { "type": "string" }, "wrappedRecoveryUserVaultKey": { "type": "string" }, "wrappedRecoveryUserVaultKeyNonce": { "type": "string" }, "recoveryVersion": { "type": "integer" }, "recoveryCreatedAt": { "type": "string", "format": "date-time" } }, "required": [ "cryptoVersion", "kdfAlgorithm", "kdfVersion", "kdfSalt", "kdfOpsLimitName", "kdfMemLimitName", "wrappedUserVaultKey", "wrappedUserVaultKeyNonce", "wrappedRecoveryUserVaultKey", "wrappedRecoveryUserVaultKeyNonce", "recoveryVersion", "recoveryCreatedAt" ] }, "MobileVaultRecord": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "cryptoVersion": { "type": "integer" }, "wrappedVaultKey": { "type": "string" }, "wrappedVaultKeyNonce": { "type": "string" } }, "required": [ "uuid", "cryptoVersion", "wrappedVaultKey", "wrappedVaultKeyNonce" ] }, "MobileVaultItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "cryptoVersion": { "type": "integer" }, "revision": { "type": "integer" }, "encryptedPayload": { "type": "string" }, "payloadNonce": { "type": "string" }, "wrappedItemKey": { "type": "string" }, "itemKeyNonce": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "cryptoVersion", "revision", "encryptedPayload", "payloadNonce", "wrappedItemKey", "itemKeyNonce", "updatedAt" ] }, "MobileVaultPage": { "type": "object", "properties": { "crypto": { "allOf": [ { "$ref": "#/components/schemas/MobileVaultCryptoRecord" } ], "nullable": true }, "vault": { "allOf": [ { "$ref": "#/components/schemas/MobileVaultRecord" } ], "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MobileVaultItem" } }, "trashed_items": { "type": "array", "items": { "$ref": "#/components/schemas/MobileVaultItem" } } }, "required": [ "crypto", "vault", "items", "trashed_items" ] }, "MobileImageConversion": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "sourceFilename": { "type": "string" }, "outputFilename": { "type": "string", "nullable": true }, "outputMimetype": { "type": "string", "nullable": true }, "formatLabel": { "type": "string", "nullable": true }, "outputWidth": { "type": "integer", "nullable": true }, "outputHeight": { "type": "integer", "nullable": true }, "outputFilesize": { "type": "integer", "nullable": true }, "outputDisplaySize": { "type": "string", "nullable": true }, "savedToMagpie": { "type": "boolean" }, "savedImage": { "allOf": [ { "$ref": "#/components/schemas/MobileImage" } ], "nullable": true }, "expired": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "downloadPath": { "type": "string" } }, "required": [ "uuid", "sourceFilename", "outputFilename", "outputMimetype", "formatLabel", "outputWidth", "outputHeight", "outputFilesize", "outputDisplaySize", "savedToMagpie", "savedImage", "expired", "expiresAt", "createdAt", "downloadPath" ] }, "MobileImageSizePreset": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "maxWidth": { "type": "integer", "nullable": true }, "ratio": { "type": "string", "nullable": true }, "format": { "type": "string", "nullable": true } }, "required": [ "key", "label", "description", "width", "height", "maxWidth", "ratio", "format" ] }, "MobileImageCropRatio": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "ratio": { "type": "number", "nullable": true } }, "required": [ "key", "label", "ratio" ] }, "MobileImageBatch": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "destination": { "type": "string", "enum": [ "zip", "magpie" ] }, "totalCount": { "type": "integer" }, "doneCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "statusPath": { "type": "string" }, "downloadPath": { "type": "string" }, "savePath": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "name", "status", "destination", "totalCount", "doneCount", "failedCount", "statusPath", "downloadPath", "savePath", "createdAt" ] }, "MobileImageBatchItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "sourceFilename": { "type": "string" }, "relativeFolder": { "type": "string", "nullable": true }, "status": { "type": "string" }, "errorMessage": { "type": "string", "nullable": true }, "outputConversionUuid": { "type": "string", "nullable": true } }, "required": [ "uuid", "sourceFilename", "relativeFolder", "status", "errorMessage", "outputConversionUuid" ] }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "channelUuid": { "type": "string" }, "parentMessageUuid": { "type": "string", "nullable": true }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "isStaff": { "type": "boolean", "description": "True for Magpie staff writing in a support conversation; set from the account, never the name." } } }, "isOwn": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "threadReplyCount": { "type": "integer" }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string" }, "count": { "type": "integer" }, "reacted": { "type": "boolean" } } } }, "images": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "filename": { "type": "string" }, "mimetype": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "displaySize": { "type": "string" } } } }, "audio": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mimetype": { "type": "string" }, "filesize": { "type": "integer" }, "displaySize": { "type": "string" }, "durationMs": { "type": "integer", "nullable": true }, "url": { "type": "string" } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mimetype": { "type": "string" }, "filesize": { "type": "integer" }, "displaySize": { "type": "string" }, "url": { "type": "string" } }, "required": [ "uuid", "filename", "mimetype", "filesize", "displaySize", "url" ] }, "maxItems": 5 } } }, "ChatHistory": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "hasOlderVisible": { "type": "boolean" }, "historyLimited": { "type": "boolean" }, "oldestVisibleMessageId": { "type": "integer", "nullable": true } } }, "ChatThread": { "type": "object", "properties": { "root": { "$ref": "#/components/schemas/ChatMessage" }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "hasOlderReplies": { "type": "boolean" } } }, "ChatEvents": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "channelUuid": { "type": "string" }, "type": { "type": "string" } } } }, "cursor": { "type": "integer" }, "hasMore": { "type": "boolean" }, "serverTime": { "type": "string" } } }, "ChatPresence": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "user_id", "name" ] } }, "ChatChannelMembers": { "type": "object", "properties": { "channelUuid": { "type": "string" }, "access": { "type": "string", "enum": [ "team", "members" ] }, "teamName": { "type": "string" }, "isGeneral": { "type": "boolean" }, "isPersonal": { "type": "boolean" }, "canManage": { "type": "boolean" }, "guestsAvailable": { "type": "boolean" }, "upgradeUrl": { "type": "string", "nullable": true }, "viewerRole": { "type": "string", "nullable": true, "enum": [ "member", "guest", null ] }, "linkDays": { "type": "integer" }, "linkMaxUses": { "type": "integer" }, "teamMemberCount": { "type": "integer", "description": "Only for a channel open to the whole team." }, "result": { "type": "string", "enum": [ "added", "invited" ], "description": "Only from add-member." }, "url": { "type": "string", "description": "Only from create-link; shown once." }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "username": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "member", "guest" ] }, "isTeamAdmin": { "type": "boolean" }, "isSelf": { "type": "boolean" } } } }, "invitations": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "createdByName": { "type": "string" }, "useCount": { "type": "integer" }, "maxUses": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "required": [ "channelUuid", "access", "canManage", "members", "invitations", "links" ] }, "ChatMemberProfile": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "role": { "type": "string", "description": "The person's role in the selected team; guest when they are a guest in one of its channels, or none when they are not in it but share a conversation with the viewer. Email and timezone are null for guest and none." }, "username": { "type": "string", "nullable": true }, "isSelf": { "type": "boolean" }, "directUuid": { "type": "string", "nullable": true }, "muted": { "type": "boolean", "description": "The viewer muted this person: their messages send no push notification and play no tab sound, and still count as unread." }, "blocked": { "type": "boolean", "description": "The viewer blocked this person: their posts, comments and messages are hidden everywhere. Change it with /users/me/blocks." } }, "required": [ "id", "name", "role", "isSelf", "muted", "blocked" ] }, "ChatConversation": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "partner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "hasUnread": { "type": "boolean" } } }, "ChatBootstrap": { "type": "object", "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ChatConversation" } }, "directMessages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatConversation" } }, "teamMembers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "eventCursor": { "type": "integer" }, "selectedChannel": { "$ref": "#/components/schemas/ChatConversation" }, "history": { "$ref": "#/components/schemas/ChatHistory" }, "currentUser": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "isAdmin": { "type": "boolean" } } }, "supportedReactions": { "type": "array", "items": { "type": "string" } }, "entitlement": { "type": "object" } } }, "Note": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "content_markdown": { "type": "string" }, "content_html": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "id": { "type": "integer" }, "user_id": { "type": "integer" }, "word_count": { "type": "integer" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } } }, "NoteDraft": { "type": "object", "properties": { "note_uuid": { "type": "string" }, "content_markdown": { "type": "string" }, "base_updated_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } }, "MobilePodcastDraft": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "podcast_uuid": { "type": "string", "format": "uuid" }, "podcast_title": { "type": "string" }, "title": { "type": "string", "description": "Empty until someone gives the draft a title" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft" ] }, "take_count": { "type": "integer" }, "duration_ms": { "type": "integer" }, "takes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "duration_ms": { "type": "integer" }, "size_bytes": { "type": "integer" }, "waveform": { "type": "array", "items": { "type": "integer" } }, "playback_path": { "type": "string" } } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "MobilePodcast": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true }, "language": { "type": "string" }, "category": { "type": "string", "nullable": true }, "explicit": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "is_enabled": { "type": "boolean" }, "web_path": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "title", "description", "author_name", "language", "category", "explicit", "image_url", "is_enabled", "web_path", "updated_at" ] }, "MobilePodcastEpisode": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time" }, "audio_mime_type": { "type": "string" }, "file_size_bytes": { "type": "integer", "minimum": 0 }, "duration_seconds": { "type": "integer", "minimum": 0, "nullable": true }, "playback_path": { "type": "string", "description": "Authenticated stream path; never a public upload URL." }, "web_path": { "type": "string" } }, "required": [ "uuid", "title", "description", "published_at", "audio_mime_type", "file_size_bytes", "duration_seconds", "playback_path", "web_path" ] }, "MobileQrDestinationInspection": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Validated http(s) destination without credentials." }, "scheme": { "type": "string", "enum": [ "http", "https" ] }, "hostname": { "type": "string" } }, "required": [ "url", "scheme", "hostname" ] }, "MobileQrDesign": { "type": "object", "additionalProperties": false, "properties": { "size": { "type": "integer", "minimum": 128, "maximum": 2048 }, "margin": { "type": "integer", "minimum": 2, "maximum": 12 }, "error_correction": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "has_logo": { "type": "boolean" } }, "required": [ "size", "margin", "error_correction", "foreground", "background", "has_logo" ] }, "MobileQrDesignUpdate": { "type": "object", "additionalProperties": false, "properties": { "size": { "type": "integer", "minimum": 128, "maximum": 2048 }, "margin": { "type": "integer", "minimum": 2, "maximum": 12 }, "error_correction": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "logo_image_uuid": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "size", "margin", "error_correction", "foreground", "background" ] }, "MobileQrCode": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "static", "dynamic" ] }, "summary": { "type": "string", "maxLength": 180 }, "destination": { "type": "string", "format": "uri", "nullable": true }, "destination_inspection": { "$ref": "#/components/schemas/MobileQrDestinationInspection", "nullable": true }, "is_enabled": { "type": "boolean" }, "scan_count": { "type": "integer", "minimum": 0 }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "web_path": { "type": "string" }, "can_edit": { "type": "boolean", "description": "Whether the viewer can edit or delete this QR code. Present on list items." } }, "required": [ "uuid", "name", "type", "mode", "summary", "destination", "destination_inspection", "is_enabled", "scan_count", "expires_at", "updated_at", "web_path" ] }, "MobileQrCodeDetail": { "allOf": [ { "$ref": "#/components/schemas/MobileQrCode" }, { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "can_edit": { "type": "boolean" }, "design": { "$ref": "#/components/schemas/MobileQrDesign" } }, "required": [ "created_at", "can_edit", "design" ] } ] }, "MobileScreenRecording": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] }, "mime_type": { "type": "string" }, "duration_ms": { "type": "integer", "minimum": 0 }, "size_bytes": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "download_available": { "type": "boolean" }, "web_path": { "type": "string", "description": "Same-origin Web viewer path; no storage URL or token." } }, "required": [ "uuid", "title", "status", "mime_type", "duration_ms", "size_bytes", "created_at", "updated_at", "download_available", "web_path" ] }, "MobileScreenRecordingAnalytics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0 }, "started_watching": { "type": "integer", "minimum": 0 }, "watched_to_end": { "type": "integer", "minimum": 0 }, "average_watched_ms": { "type": "integer", "minimum": 0 }, "average_watched_percent": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "play_rate": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "link_clicks": { "type": "integer", "minimum": 0 }, "downloads": { "type": "integer", "minimum": 0 }, "last_viewed_at": { "type": "string", "format": "date-time", "nullable": true }, "watch_depth": { "type": "array", "items": { "type": "object", "properties": { "percent": { "type": "integer" }, "visits": { "type": "integer", "minimum": 0 }, "share": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "percent", "visits", "share" ] } }, "links": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "label": { "type": "string" }, "clicks": { "type": "integer", "minimum": 0 }, "visits": { "type": "integer", "minimum": 0 } }, "required": [ "label", "clicks", "visits" ] } }, "referrers": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "hostname": { "type": "string" }, "views": { "type": "integer", "minimum": 0 } }, "required": [ "hostname", "views" ] } }, "timeline": { "type": "array", "maxItems": 30, "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "views": { "type": "integer", "minimum": 0 }, "plays": { "type": "integer", "minimum": 0 } }, "required": [ "day", "views", "plays" ] } } }, "required": [ "views", "started_watching", "watched_to_end", "average_watched_ms", "average_watched_percent", "play_rate", "link_clicks", "downloads", "last_viewed_at", "watch_depth", "links", "referrers", "timeline" ] }, "MobileScreenRecordingShareLink": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "primary": { "type": "boolean" } }, "required": [ "label", "url", "primary" ] }, "MobileScreenRecordingShareSettings": { "type": "object", "properties": { "share_path": { "type": "string" }, "share_slug": { "type": "string", "nullable": true, "maxLength": 80 }, "show_download_button": { "type": "boolean" }, "links": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/MobileScreenRecordingShareLink" } }, "transcript_document_uuid": { "type": "string", "format": "uuid", "nullable": true }, "form_uuid": { "type": "string", "format": "uuid", "nullable": true }, "web_path": { "type": "string" } }, "required": [ "share_path", "share_slug", "show_download_button", "links", "transcript_document_uuid", "form_uuid", "web_path" ] }, "MobileScreenRecordingShareOptions": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "scope_label": { "type": "string" } }, "required": [ "uuid", "title", "scope_label" ] } }, "forms": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } }, "required": [ "uuid", "title" ] } } }, "required": [ "documents", "forms" ] }, "MobileRepositoryTeam": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "MobileRepository": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true, "maxLength": 1000 }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "default_branch": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "archived" ] }, "team": { "$ref": "#/components/schemas/MobileRepositoryTeam" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "web_path": { "type": "string" }, "clone_url": { "type": "string", "format": "uri" }, "can_write": { "type": "boolean" } }, "required": [ "uuid", "name", "slug", "description", "visibility", "default_branch", "state", "team", "created_at", "updated_at", "web_path", "clone_url" ] }, "MobileSupporterTier": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "benefits": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "uuid", "name", "description", "benefits", "is_active", "created_at", "updated_at" ] }, "MobileSupporterSubscriber": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tier_name": { "type": "string" }, "status": { "type": "string" }, "is_entitled": { "type": "boolean" }, "cancel_at_period_end": { "type": "boolean" }, "current_period_end": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "uuid", "name", "tier_name", "status", "is_entitled", "cancel_at_period_end", "current_period_end", "created_at" ] }, "MobileSupportersOverview": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "active" ] }, "is_published": { "type": "boolean" }, "tier_count": { "type": "integer", "minimum": 0 }, "published_post_count": { "type": "integer", "minimum": 0 }, "subscriber_count": { "type": "integer", "minimum": 0 }, "tiers": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileSupporterTier" } }, "subscribers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileSupporterSubscriber" } }, "can_manage_on_web": { "type": "boolean" }, "web_path": { "type": "string" }, "public_path": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "uuid", "name", "description", "status", "is_published", "tier_count", "published_post_count", "subscriber_count", "tiers", "subscribers", "can_manage_on_web", "web_path", "public_path", "updated_at" ] }, "MobileSupporterSubscription": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "program_uuid": { "type": "string", "format": "uuid" }, "program_name": { "type": "string" }, "team_name": { "type": "string" }, "tier_name": { "type": "string" }, "status": { "type": "string" }, "is_entitled": { "type": "boolean" }, "cancel_at_period_end": { "type": "boolean" }, "current_period_end": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "program_is_published": { "type": "boolean" }, "web_path": { "type": "string" } }, "required": [ "uuid", "program_uuid", "program_name", "team_name", "tier_name", "status", "is_entitled", "cancel_at_period_end", "current_period_end", "created_at", "program_is_published", "web_path" ] }, "MobileWebsiteLink": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string", "maxLength": 2048 } }, "required": [ "label", "url" ] }, "MobileIdeaWorkspaceItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "note", "todo", "link", "image", "comment", "column", "connector" ] }, "x": { "type": "integer" }, "y": { "type": "integer" }, "width": { "type": "integer", "minimum": 120 }, "z_index": { "type": "integer", "minimum": 0 }, "sort_order": { "type": "integer", "minimum": 0 }, "locked": { "type": "boolean" }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Bounded display metadata; raw item content and identifiers are omitted." } }, "required": [ "uuid", "type", "x", "y", "width", "z_index", "sort_order", "locked", "parent_uuid", "metadata" ] }, "MobileIdeaWorkspace": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 255 }, "updated_at": { "type": "string", "format": "date-time" }, "web_path": { "type": "string" }, "can_edit": { "type": "boolean" }, "item_count": { "type": "integer", "minimum": 0 }, "items_truncated": { "type": "boolean" }, "items": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileIdeaWorkspaceItem" } } }, "required": [ "uuid", "title", "updated_at", "web_path", "can_edit" ] }, "MobileWebsite": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "is_published": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "creator_name": { "type": "string", "nullable": true }, "public_url": { "type": "string" }, "web_path": { "type": "string" }, "can_edit": { "type": "boolean" }, "links": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileWebsiteLink" } } }, "required": [ "uuid", "title", "slug", "status", "is_published", "version", "created_at", "updated_at", "creator_name", "public_url", "web_path", "can_edit" ] }, "MobileWebsiteStatus": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "is_published": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1 }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "status", "is_published", "version", "updated_at" ] }, "Team": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "blue", "teal", "purple", "orange", "green", "indigo", "gold", "pink" ] }, "is_personal": { "type": "boolean" }, "role": { "type": "string" }, "default_member_access": { "type": "string" }, "is_default": { "type": "boolean" }, "is_owner": { "type": "boolean" } } }, "MobileTeamMember": { "type": "object", "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "is_current_user": { "type": "boolean" }, "is_owner": { "type": "boolean" } }, "required": [ "user_id", "name", "email", "role", "is_current_user", "is_owner" ] }, "MobileTeamInvitation": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "expires_at": { "type": "string" } }, "required": [ "uuid", "email", "role", "expires_at" ] }, "MobileTeamInvitationDetails": { "type": "object", "properties": { "team": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "uuid", "name" ] }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "expires_at": { "type": "string" } }, "required": [ "team", "role", "expires_at" ] }, "TeamContext": { "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "current_team_id": { "type": "integer" } } }, "Dashboard": { "type": "object", "properties": { "pinned_keys": { "type": "array", "items": { "type": "string" } }, "recent_tool_keys": { "type": "array", "items": { "type": "string" } }, "recent_items": { "type": "array", "items": { "type": "object", "properties": { "feature_key": { "type": "string" }, "object_key": { "type": "string", "description": "With feature_key and team.id, identifies the item for POST /dashboard/recent/remove." }, "title": { "type": "string" }, "url": { "type": "string" }, "type_label": { "type": "string" }, "status": { "type": "string" }, "activity_kind": { "type": "string" }, "activity_at": { "type": "string" }, "team": { "$ref": "#/components/schemas/TeamReference" } } } }, "notes": { "type": "object", "nullable": true, "description": "The latest Notes from Personal and every team where Notes can be used. Null when hidden from Dashboard or when Notes cannot be used in any team.", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "preview": { "type": "string" }, "updated_at": { "type": "string" }, "team": { "$ref": "#/components/schemas/TeamReference" } } } }, "can_create": { "type": "boolean" }, "failed": { "type": "boolean" } } }, "unread_mail": { "type": "object", "nullable": true, "description": "Mailboxes with unread mail from Personal and every team. Null when hidden from Dashboard or for someone with no mailbox.", "properties": { "mailboxes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "address": { "type": "string" }, "unread": { "type": "integer" }, "team": { "$ref": "#/components/schemas/TeamReference" } } } }, "failed": { "type": "boolean" } } }, "todos": { "type": "object", "nullable": true, "description": "Today's To-dos, then the next ones planned, from Personal, every team and Lists shared with the person. Null when hidden from Dashboard.", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "is_today": { "type": "boolean" }, "day": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "deadline": { "type": "string", "nullable": true }, "deadline_passed": { "type": "boolean" }, "is_important": { "type": "boolean" }, "is_recurring": { "type": "boolean" }, "assignee_name": { "type": "string", "nullable": true }, "checklist": { "type": "string", "nullable": true }, "list_name": { "type": "string", "nullable": true }, "can_complete": { "type": "boolean" }, "team": { "$ref": "#/components/schemas/TeamReference" } } } }, "more_today": { "type": "integer" }, "more_upcoming": { "type": "integer" }, "can_add": { "type": "boolean" }, "failed": { "type": "boolean" } } } } }, "TeamReference": { "type": "object", "description": "The Personal-or-team selection a cross-team result belongs to. Open it with that team selected.", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "name": { "type": "string", "description": "Display label: Personal, or the team's name." }, "is_personal": { "type": "boolean" } } }, "SearchResults": { "type": "object", "properties": { "query": { "type": "string", "description": "The query that ran, trimmed; empty when it was too short." }, "min_query_length": { "type": "integer" }, "types": { "type": "array", "description": "What this person can search in, in display order.", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } } } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "more": { "type": "boolean", "description": "More matches exist than are listed; search this type alone to see them." }, "incomplete": { "type": "boolean", "description": "Some teams could not be searched for this type." }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "type_label": { "type": "string" }, "url": { "type": "string", "description": "Website path." }, "app_path": { "type": "string", "description": "Native app route for the same item." }, "updated_at": { "type": "string", "nullable": true }, "team": { "$ref": "#/components/schemas/TeamReference" } } } } } } } } }, "MobileAuthSession": { "type": "object", "properties": { "token": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" } } }, "MobileTwoFactorChallenge": { "type": "object", "properties": { "two_factor_required": { "type": "boolean", "enum": [ true ] }, "two_factor_token": { "type": "string" } } }, "MobileSignInCheckRequired": { "type": "object", "properties": { "sign_in_check_required": { "type": "boolean", "enum": [ true ] }, "sign_in_check_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "MobileEmailCodeRequest": { "type": "object", "properties": { "sign_in_request": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Kept by the app and sent back with the code." }, "minutes": { "type": "integer", "description": "How long the code works." } } }, "MobileSignInCheckDetails": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "how": { "type": "string", "enum": [ "provider", "email_link" ] }, "provider": { "type": "string", "nullable": true, "description": "The provider's name; null after a code from an email." }, "set_up": { "type": "object", "description": "What is set up on the account: password, two_factor, passkeys, providers, apps, api_keys, git_tokens, ssh_keys, email_change, devices, webhooks, connections, shift_feed and the last five sign_ins." } } }, "EmailConfirmed": { "type": "object", "properties": { "confirmed": { "type": "boolean", "enum": [ true ] }, "removed": { "type": "boolean" }, "user": { "$ref": "#/components/schemas/User" } } }, "KanbanCard": { "type": "object", "properties": { "public_id": { "type": "string" }, "column_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "assignee_name": { "type": "string", "nullable": true }, "due_date": { "type": "string", "nullable": true }, "comment_count": { "type": "integer" }, "is_suggestion": { "type": "boolean" }, "edit_token": { "type": "string" }, "images": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/KanbanImage" } } } }, "KanbanImage": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true } } }, "KanbanColumn": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_inbox": { "type": "boolean" }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanCard" } } } }, "MobileKanbanBoard": { "type": "object", "properties": { "uuid": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "card_count": { "type": "integer" }, "can_edit": { "type": "boolean" }, "external_access": { "type": "string" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanColumn" } } } }, "MobileDocument": { "type": "object", "properties": { "uuid": { "type": "string" }, "title": { "type": "string" }, "revision": { "type": "integer" }, "creator_name": { "type": "string" }, "workspace_name": { "type": "string" }, "is_shared": { "type": "boolean" }, "team_id": { "type": "integer" }, "can_move": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_comment": { "type": "boolean" }, "can_review": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "authoring": { "type": "object", "additionalProperties": true } } }, "pictures": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mimetype": { "type": "string" }, "filesize": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true } } } } }, "required": [ "uuid", "title", "revision", "creator_name", "workspace_name", "is_shared", "can_edit", "can_comment", "can_review", "updated_at" ] }, "MobileSpreadsheetSheet": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sort_order": { "type": "integer" }, "is_hidden": { "type": "boolean" }, "tab_color": { "type": "string", "nullable": true }, "frozen_rows": { "type": "integer", "minimum": 0 }, "frozen_columns": { "type": "integer", "minimum": 0 } }, "required": [ "uuid", "name", "sort_order", "is_hidden", "frozen_rows", "frozen_columns" ] }, "MobileSpreadsheet": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "revision": { "type": "integer", "minimum": 0 }, "creator_name": { "type": "string" }, "workspace_name": { "type": "string" }, "is_shared": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" }, "web_path": { "type": "string" } }, "required": [ "uuid", "title", "revision", "creator_name", "workspace_name", "is_shared", "updated_at", "web_path" ] }, "MobileSpreadsheetDetail": { "allOf": [ { "$ref": "#/components/schemas/MobileSpreadsheet" }, { "type": "object", "properties": { "locale": { "type": "string" }, "timezone": { "type": "string" }, "can_edit": { "type": "boolean" }, "can_comment": { "type": "boolean" }, "can_manage": { "type": "boolean" }, "sheets": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetSheet" } } }, "required": [ "locale", "timezone", "can_edit", "can_comment", "can_manage", "sheets" ] } ] }, "MobileSpreadsheetPreview": { "type": "object", "properties": { "sheet": { "$ref": "#/components/schemas/MobileSpreadsheetSheet" }, "rows": { "type": "integer", "const": 20 }, "columns": { "type": "integer", "const": 10 }, "cells": { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "row": { "type": "integer", "minimum": 0, "maximum": 19 }, "column": { "type": "integer", "minimum": 0, "maximum": 9 }, "content": { "type": "string", "maxLength": 500 }, "content_truncated": { "type": "boolean" }, "is_formula": { "type": "boolean" }, "style": { "type": "object", "additionalProperties": true } }, "required": [ "row", "column", "content", "content_truncated", "is_formula", "style" ] } }, "truncated": { "type": "boolean" }, "formulas_evaluated": { "type": "boolean", "const": false } }, "required": [ "sheet", "rows", "columns", "cells", "truncated", "formulas_evaluated" ] }, "MobileSpreadsheetCellUpdate": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "operationId": { "type": "string", "format": "uuid" }, "sheetUuid": { "type": "string", "format": "uuid" }, "row": { "type": "integer", "minimum": 0, "maximum": 99999 }, "column": { "type": "integer", "minimum": 0, "maximum": 999 }, "content": { "type": "string", "maxLength": 50000 }, "style": { "type": "object", "additionalProperties": true } }, "required": [ "revision", "operationId", "sheetUuid", "row", "column", "content" ] }, "MobileSpreadsheetSheetUpdate": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "operationId": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "addSheet", "renameSheet", "duplicateSheet", "deleteSheet", "hideSheet", "unhideSheet", "moveSheet", "renameWorkbook" ] }, "sheetUuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100 }, "title": { "type": "string", "maxLength": 150 }, "position": { "type": "integer", "minimum": 0 } }, "required": [ "revision", "operationId", "operation" ] }, "MobileSpreadsheetCollaborator": { "type": "object", "properties": { "user_id": { "type": "integer", "minimum": 1 }, "username": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "viewer", "commenter", "editor" ] } }, "required": [ "user_id", "username", "name", "access" ] }, "MobileSpreadsheetFilterView": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sheetUuid": { "type": "string", "format": "uuid" }, "sheetName": { "type": "string" }, "view": { "type": "object", "additionalProperties": true }, "updatedAt": { "type": "string" } }, "required": [ "uuid", "name", "sheetUuid", "sheetName", "view", "updatedAt" ] }, "MobileSpreadsheetFilterViewInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "sheetUuid": { "type": "string", "format": "uuid" }, "filter": { "type": [ "object", "null" ], "additionalProperties": true }, "sortColumn": { "type": "integer", "minimum": 0, "maximum": 999 }, "direction": { "type": "string", "enum": [ "none", "ascending", "descending" ] }, "rowStart": { "type": "integer", "minimum": 0, "maximum": 99999 }, "rowEnd": { "type": "integer", "minimum": 0, "maximum": 99999 }, "columnStart": { "type": "integer", "minimum": 0, "maximum": 999 }, "columnEnd": { "type": "integer", "minimum": 0, "maximum": 999 }, "hasHeader": { "type": "boolean" } }, "required": [ "name", "sheetUuid", "filter", "sortColumn", "direction", "rowStart", "rowEnd", "columnStart", "columnEnd", "hasHeader" ], "additionalProperties": false }, "MobileSpreadsheetFindMatch": { "type": "object", "properties": { "sheetUuid": { "type": "string", "format": "uuid" }, "sheetName": { "type": "string" }, "row": { "type": "integer", "minimum": 0 }, "column": { "type": "integer", "minimum": 0 }, "content": { "type": "string" }, "style": { "type": "object", "additionalProperties": true } }, "required": [ "sheetUuid", "sheetName", "row", "column", "content", "style" ] }, "DocumentCollaborator": { "type": "object", "properties": { "user_id": { "type": "integer" }, "username": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "viewer", "reviewer", "editor" ] } }, "required": [ "user_id", "username", "name", "access" ] }, "DocumentComment": { "type": "object", "properties": { "uuid": { "type": "string" }, "parent_uuid": { "type": "string", "nullable": true }, "can_resolve": { "type": "boolean" }, "author_name": { "type": "string" }, "body_markdown": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "created_at": { "type": "string" } }, "required": [ "uuid", "parent_uuid", "can_resolve", "author_name", "body_markdown", "status", "created_at" ] }, "DocumentSuggestion": { "type": "object", "properties": { "uuid": { "type": "string" }, "author_name": { "type": "string" }, "original_text": { "type": "string" }, "suggested_text": { "type": "string" }, "suggestion_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "can_decide": { "type": "boolean" } }, "required": [ "uuid", "author_name", "original_text", "suggested_text", "suggestion_type", "status", "created_at", "can_decide" ] }, "DocumentOperation": { "type": "object", "properties": { "uuid": { "type": "string" }, "actor_name": { "type": "string" }, "base_revision": { "type": "integer" }, "revision": { "type": "integer" }, "operation_type": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "uuid", "actor_name", "base_revision", "revision", "operation_type", "created_at" ] }, "DocumentVersion": { "type": "object", "properties": { "uuid": { "type": "string" }, "name": { "type": "string", "nullable": true }, "revision": { "type": "integer" }, "author_name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "uuid", "name", "revision", "author_name", "created_at" ] }, "DocumentAccessibilityIssue": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "blockId": { "type": "string" }, "index": { "type": "integer", "minimum": 0 } }, "required": [ "severity", "code", "message", "blockId", "index" ] }, "DocumentAccessibilityReport": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAccessibilityIssue" } }, "summary": { "type": "object", "properties": { "errors": { "type": "integer", "minimum": 0 }, "warnings": { "type": "integer", "minimum": 0 } }, "required": [ "errors", "warnings" ] } }, "required": [ "issues", "summary" ] }, "MobileForm": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "closed" ] }, "response_count": { "type": "integer", "minimum": 0 }, "view_count": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string" }, "created_at": { "type": "string" }, "draft_version": { "type": "integer", "minimum": 1 }, "can_edit": { "type": "boolean" }, "web_path": { "type": "string" } }, "required": [ "uuid", "title", "status", "response_count", "view_count", "updated_at", "can_edit", "web_path" ] }, "MobileFormBuilder": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 150 }, "draft_version": { "type": "integer", "minimum": 1 }, "schema": { "type": "object", "additionalProperties": true } }, "required": [ "title", "draft_version", "schema" ] }, "MobileFormPayment": { "type": "object", "properties": { "draft_version": { "type": "integer", "minimum": 1 }, "enabled": { "type": "boolean" }, "amount": { "type": "string", "maxLength": 20 }, "currency": { "type": "string" }, "currencies": { "type": "object", "additionalProperties": { "type": "string" } }, "fee_basis_points": { "type": "integer", "minimum": 0 } }, "required": [ "draft_version", "enabled", "amount", "currency", "currencies", "fee_basis_points" ] }, "MobileFormSettings": { "type": "object", "properties": { "authenticated_only": { "type": "boolean" }, "one_response_per_user": { "type": "boolean" }, "notify_on_submission": { "type": "boolean" } }, "required": [ "authenticated_only", "one_response_per_user", "notify_on_submission" ] }, "MobileFormAppearance": { "type": "object", "properties": { "theme": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label", "description" ] } } }, "required": [ "theme", "choices" ] }, "MobileFormCollaborator": { "type": "object", "properties": { "user_id": { "type": "integer", "minimum": 1 }, "username": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "view", "edit" ] } }, "required": [ "user_id", "username", "name", "access" ] }, "MobileFormSummary": { "type": "object", "properties": { "responseCount": { "type": "integer", "minimum": 0 }, "pages": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "title", "fields" ] } } }, "required": [ "responseCount", "pages" ] }, "MobileFormResponse": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "reviewed", "archived" ] }, "payment_state": { "type": "string", "nullable": true }, "payment_amount": { "type": "integer", "minimum": 0, "nullable": true }, "payment_currency": { "type": "string", "nullable": true }, "can_edit": { "type": "boolean" }, "web_path": { "type": "string" } }, "required": [ "uuid", "submitted_at", "status", "payment_state", "payment_amount", "payment_currency", "can_edit", "web_path" ] }, "MobileFormResponseField": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "file": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "web_path": { "type": "string" } }, "required": [ "uuid", "name", "web_path" ] } }, "required": [ "id", "label", "type" ] }, "MobileFormResponseDetail": { "allOf": [ { "$ref": "#/components/schemas/MobileFormResponse" }, { "type": "object", "properties": { "payment": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "state": { "type": "string" }, "amount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" } }, "required": [ "state", "amount", "currency" ] }, "pages": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 300 }, "fields": { "type": "array", "maxItems": 400, "items": { "$ref": "#/components/schemas/MobileFormResponseField" } } }, "required": [ "title", "fields" ] } }, "truncated": { "type": "boolean" } }, "required": [ "payment", "pages", "truncated" ] } ] }, "MobileSecuritySession": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100 }, "status": { "type": "string", "enum": [ "active" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "is_current": { "type": "boolean" } }, "required": [ "id", "uuid", "name", "status", "expires_at", "last_used_at", "created_at", "is_current" ] }, "MobileBillingUsage": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0, "nullable": true }, "display": { "type": "string" } }, "required": [ "key", "label", "used", "limit", "display" ] }, "MobileBillingStatus": { "type": "object", "properties": { "context": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_personal": { "type": "boolean" }, "uses_owner_plan": {"type": "boolean"}, "is_owner": {"type": "boolean"}, "covers_owned_teams": {"type": "boolean"} }, "required": [ "uuid", "name", "is_personal" ] }, "plan": { "type": "string", "enum": [ "Free", "Pro", "Team" ] }, "status": { "type": "string", "enum": [ "active", "trialing", "past_due", "canceled", "none" ] }, "renewal_at": { "type": "string", "format": "date-time", "nullable": true }, "cancel_at_period_end": { "type": "boolean" }, "billing_source": { "type": "string", "enum": ["stripe", "apple", "google"], "nullable": true }, "mobile_store": {"type": "string", "enum": ["apple", "google"], "nullable": true}, "can_purchase": {"type": "boolean"}, "purchase_account_token": {"type": "string", "format": "uuid", "nullable": true}, "purchase_team_id": {"type": "integer", "nullable": true}, "purchase_products": { "type": "array", "items": {"type": "string"}, "minItems": 2, "maxItems": 2 }, "purchase_product_id": {"type": "string", "nullable": true}, "pro_benefits": {"type": "array", "items": {"type": "string"}, "maxItems": 10}, "legal_urls": {"type": "object", "properties": { "terms": {"type": "string", "format": "uri"}, "privacy": {"type": "string", "format": "uri"} }, "required": ["terms", "privacy"]}, "usage": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileBillingUsage" } }, "web_path": { "type": "string" } }, "required": [ "context", "plan", "status", "renewal_at", "cancel_at_period_end", "billing_source", "mobile_store", "can_purchase", "purchase_account_token", "purchase_products", "purchase_product_id", "purchase_team_id", "pro_benefits", "legal_urls", "usage", "web_path" ] }, "MobileLegalDocument": { "type": "object", "properties": { "data": {"type": "object", "properties": { "title": {"type": "string"}, "content": {"type": "string"}, "url": {"type": "string", "format": "uri"} }, "required": ["title", "content", "url"]} }, "required": ["data"] }, "MobilePurchaseSyncResponse": { "type": "object", "properties": {"data": {"type": "object", "properties": { "purchase": {"type": "object", "properties": { "store": {"type": "string", "enum": ["apple", "google"]}, "productId": {"type": "string"}, "status": {"type": "string"}, "expiresAt": {"type": "string", "format": "date-time", "nullable": true}, "cancelAtPeriodEnd": {"type": "boolean"}, "overlapping": {"type": "boolean"} }, "required": ["store", "productId", "status", "expiresAt", "cancelAtPeriodEnd", "overlapping"]}, "billing": {"$ref": "#/components/schemas/MobileBillingStatus"} }, "required": ["purchase", "billing"]}}, "required": ["data"] }, "MobileDataRemovalCoverage": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string" }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true }, "next_check_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "name", "domain", "status", "last_checked_at", "next_check_at" ] }, "MobileDataRemovalRequest": { "type": "object", "properties": { "site_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "site_name", "status", "created_at", "updated_at" ] }, "MobileDataRemovalStatus": { "type": "object", "properties": { "exists": { "type": "boolean" }, "state": { "type": "string", "enum": [ "setup_incomplete", "pending_approval", "active" ] }, "mode": { "type": "string", "enum": [ "demo", "manual", "production" ], "nullable": true }, "review_after": { "type": "string", "format": "date-time", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "summary": { "type": "object", "properties": { "sites_checked": { "type": "integer", "minimum": 0 }, "records_found": { "type": "integer", "minimum": 0 }, "removals_submitted": { "type": "integer", "minimum": 0 }, "removed": { "type": "integer", "minimum": 0 }, "attention": { "type": "integer", "minimum": 0 } }, "required": [ "sites_checked", "records_found", "removals_submitted", "removed", "attention" ] }, "coverage": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/MobileDataRemovalCoverage" } }, "requests": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileDataRemovalRequest" } }, "open_actions": { "type": "integer", "minimum": 0 }, "queue": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "processing": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "processing", "succeeded", "failed" ] }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "web_path": { "type": "string" } }, "required": [ "exists", "state", "summary", "coverage", "requests", "open_actions", "queue", "updated_at", "web_path" ] } }, "parameters": { "StoreIdempotencyKey": {"in": "header", "name": "Idempotency-Key", "required": false, "description": "1 to 255 visible ASCII characters. A repeated POST with the same key and body returns the first answer for a day instead of acting again.", "schema": {"type": "string", "maxLength": 255}}, "StorePage": {"in": "query", "name": "page", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 1}}, "StorePerPage": {"in": "query", "name": "per_page", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, "TeamScope": { "in": "header", "name": "X-Magpie-Team-ID", "required": false, "description": "Selected team; membership is checked. Omit to use the account default. Bookings remain account-owned.", "schema": { "type": "integer", "minimum": 1 } } } }, "paths": { "/courses": {"get": {"summary": "List the selected team's courses", "tags": ["Courses API"], "description": "Newest first. Every member who can use Courses in the team reads them. Answers 403 forbidden for an account that cannot use Courses yet.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "state", "in": "query", "required": false, "schema": {"type": "string", "enum": ["draft", "published", "archived"]}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of courses", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/CourseApiCourse"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/courses/{uuid}": {"get": {"summary": "Read a course with its cohorts", "tags": ["Courses API"], "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The course", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/CourseApiCourseDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/courses/{uuid}/enrolments": {"get": {"summary": "List a course's enrolments", "tags": ["Courses API"], "description": "Needs edit rights on the course. Oldest first. Without state, every state but declined. email is an exact address; an erased student is never found by it.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "state", "in": "query", "required": false, "schema": {"type": "string", "enum": ["active", "waiting", "completed", "ended", "declined"]}}, {"name": "email", "in": "query", "required": false, "schema": {"type": "string", "format": "email", "maxLength": 254}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of enrolments", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/CourseApiEnrolment"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"summary": "Give someone access to a course", "tags": ["Courses API"], "description": "Needs edit rights on the course and the key owner's confirmed email address. Finds the account by address or makes one, and emails an invitation unless send_email is false. A cohort course needs cohort; a self-paced course refuses it. ends_at is a date (the end of that day in the course's time zone) or a time with Z or an offset; without it the course's access length applies. Someone who already has access answers 200 with already: true and nothing changes. A school adds at most 2,000 people a day (429 with Retry-After).", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"email": {"type": "string", "format": "email", "maxLength": 254}, "name": {"type": "string", "nullable": true, "maxLength": 255}, "cohort": {"type": "string", "format": "uuid", "nullable": true}, "ends_at": {"type": "string", "nullable": true, "description": "2027-10-03, or 2027-10-03T17:00:00Z"}, "send_email": {"type": "boolean", "default": true}}, "required": ["email"]}}}}, "responses": {"201": {"description": "Access was added", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"allOf": [{"$ref": "#/components/schemas/CourseApiEnrolment"}, {"type": "object", "properties": {"grant": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "ends_at": {"type": "string", "format": "date-time", "nullable": true}}}}}]}, "created_account": {"type": "boolean"}, "held": {"type": "boolean", "description": "The account's address waits for confirmation; access starts once it is confirmed."}}, "required": ["data", "created_account", "held"]}}}}, "200": {"description": "They already had access; nothing changed", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/CourseApiEnrolment"}, "already": {"type": "boolean"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/courses/{uuid}/enrolments/{enrolmentUuid}/end": {"post": {"summary": "End a student's access", "tags": ["Courses API"], "description": "Needs edit rights on the course. scope api (the default) ends only the access the API gave; all ends every way the student has access. Progress is kept. Ending again answers ended_grants 0.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "enrolmentUuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"scope": {"type": "string", "enum": ["api", "all"], "default": "api"}}}}}}, "responses": {"200": {"description": "The enrolment after the change", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/CourseApiEnrolment"}, "ended_grants": {"type": "integer"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-customers": {"get": {"summary": "List the Store's customers", "tags": ["Store API"], "description": "Needs Manage customers. Customers with the most recent order first. q matches name or email.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 200}}, {"name": "tag", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 60}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of customers", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiCustomer"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-customers/{uuid}": {"get": {"summary": "Read a customer with their saved addresses and orders", "tags": ["Store API"], "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The customer", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiCustomerDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-discounts": {"get": {"summary": "List the Store's discounts", "tags": ["Store API"], "description": "Needs Manage discounts. Newest first. status all (the default) leaves archived discounts out. q matches name or code.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["all", "active", "scheduled", "expired", "draft", "archived"]}}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 100}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of discounts", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiDiscount"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"summary": "Add a discount", "tags": ["Store API"], "description": "Needs Manage discounts. Creates the discount as a draft through StoreDiscountService, then applies the other fields in one transaction; a refused field answers 422 naming it and nothing is saved. Send status active to turn it on.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"method": {"type": "string", "enum": ["code", "automatic"]}, "title": {"type": "string", "maxLength": 150}, "code": {"type": "string", "maxLength": 40, "description": "3 to 40 letters, numbers, - or _; stored in upper case. A code discount only."}, "kind": {"type": "string", "enum": ["percentage", "fixed_amount", "free_shipping", "buy_x_get_y"]}, "percent_basis_points": {"type": "integer", "minimum": 1, "maximum": 10000, "description": "For percentage and buy_x_get_y (10000 is free)."}, "amount_off": {"type": "integer", "minimum": 1, "description": "For fixed_amount, in minor units."}, "buy_quantity": {"type": "integer", "minimum": 1}, "get_quantity": {"type": "integer", "minimum": 1}, "product_ids": {"type": "array", "maxItems": 500, "items": {"type": "string", "format": "uuid"}, "description": "Replaces the chosen Products."}, "collection_ids": {"type": "array", "maxItems": 500, "items": {"type": "string", "format": "uuid"}, "description": "Replaces the chosen Collections."}, "applies_to": {"type": "string", "enum": ["order", "products", "collections"]}, "minimum_type": {"type": "string", "enum": ["none", "subtotal", "quantity"]}, "minimum_subtotal_amount": {"type": "integer", "minimum": 1}, "minimum_quantity": {"type": "integer", "minimum": 1}, "max_applications_per_order": {"type": "integer", "nullable": true}, "usage_limit": {"type": "integer", "nullable": true}, "per_customer_limit": {"type": "integer", "nullable": true}, "starts_at": {"type": "string", "format": "date-time", "nullable": true, "description": "null starts it now."}, "ends_at": {"type": "string", "format": "date-time", "nullable": true}, "combinable": {"type": "boolean"}, "segment": {"type": "string", "format": "uuid", "nullable": true, "description": "A customer segment's uuid, or null for every customer."}, "status": {"type": "string", "enum": ["draft", "active", "archived"], "description": "Applied last; active needs a complete discount."}}, "required": ["method"], "description": "A code discount needs code; an automatic discount needs title."}}}}, "responses": {"201": {"description": "The new discount", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiDiscountDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-discounts/{uuid}": {"get": {"summary": "Read a discount with its Products, Collections, segment and uses", "tags": ["Store API"], "description": "Needs Manage discounts.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The discount", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiDiscountDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "patch": {"summary": "Change a discount", "tags": ["Store API"], "description": "Needs Manage discounts. Send only the fields to change. All are applied in one transaction; an active discount must still be complete afterwards. A code used on orders cannot be renamed.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 150}, "code": {"type": "string", "maxLength": 40, "description": "3 to 40 letters, numbers, - or _; stored in upper case. A code discount only."}, "kind": {"type": "string", "enum": ["percentage", "fixed_amount", "free_shipping", "buy_x_get_y"]}, "percent_basis_points": {"type": "integer", "minimum": 1, "maximum": 10000, "description": "For percentage and buy_x_get_y (10000 is free)."}, "amount_off": {"type": "integer", "minimum": 1, "description": "For fixed_amount, in minor units."}, "buy_quantity": {"type": "integer", "minimum": 1}, "get_quantity": {"type": "integer", "minimum": 1}, "product_ids": {"type": "array", "maxItems": 500, "items": {"type": "string", "format": "uuid"}, "description": "Replaces the chosen Products."}, "collection_ids": {"type": "array", "maxItems": 500, "items": {"type": "string", "format": "uuid"}, "description": "Replaces the chosen Collections."}, "applies_to": {"type": "string", "enum": ["order", "products", "collections"]}, "minimum_type": {"type": "string", "enum": ["none", "subtotal", "quantity"]}, "minimum_subtotal_amount": {"type": "integer", "minimum": 1}, "minimum_quantity": {"type": "integer", "minimum": 1}, "max_applications_per_order": {"type": "integer", "nullable": true}, "usage_limit": {"type": "integer", "nullable": true}, "per_customer_limit": {"type": "integer", "nullable": true}, "starts_at": {"type": "string", "format": "date-time", "nullable": true, "description": "null starts it now."}, "ends_at": {"type": "string", "format": "date-time", "nullable": true}, "combinable": {"type": "boolean"}, "segment": {"type": "string", "format": "uuid", "nullable": true, "description": "A customer segment's uuid, or null for every customer."}, "status": {"type": "string", "enum": ["draft", "active", "archived"], "description": "Applied last; active needs a complete discount."}}}}}}, "responses": {"200": {"description": "The discount", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiDiscountDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-discounts/{uuid}/deactivate": {"post": {"summary": "Deactivate a discount", "tags": ["Store API"], "description": "Needs Manage discounts. Archives the discount: it stops applying at checkout and is kept with its uses. PATCH status active turns it on again.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}], "responses": {"200": {"description": "The discount", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiDiscountDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-orders": {"get": {"summary": "List the selected team's Store orders", "tags": ["Store API"], "description": "Newest first. Needs the See orders Store permission. q matches the order number, customer name or email. from and to are dates (inclusive) compared with when the order was created.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 200}}, {"name": "payment", "in": "query", "required": false, "schema": {"type": "string", "enum": ["pending", "paid", "failed", "canceled", "partially_refunded", "refunded"]}}, {"name": "fulfillment", "in": "query", "required": false, "schema": {"type": "string", "enum": ["unfulfilled", "partially_fulfilled", "fulfilled", "canceled"]}}, {"name": "channel", "in": "query", "required": false, "schema": {"type": "string", "enum": ["online", "manual", "in_person"]}}, {"name": "tag", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 60}}, {"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date"}}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date"}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of orders", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiOrder"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-orders/{uuid}": {"get": {"summary": "Read a Store order with its items, shipments, refunds, returns and history", "tags": ["Store API"], "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The order", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiOrderDetail"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-orders/{uuid}/fulfillments": {"post": {"summary": "Add a shipment", "tags": ["Store API"], "description": "Needs Ship and edit orders. Without items, everything that remains to ship goes in this shipment. The customer is emailed about it, and store.order.fulfilled is sent.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"carrier": {"type": "string", "maxLength": 100}, "tracking_number": {"type": "string", "maxLength": 255}, "tracking_url": {"type": "string", "format": "uri", "description": "HTTPS only."}, "items": {"type": "array", "items": {"type": "object", "properties": {"item_id": {"type": "integer"}, "quantity": {"type": "integer", "minimum": 0}}, "required": ["item_id", "quantity"]}}, "location": {"type": "string", "format": "uuid", "description": "The active stock location it ships from. Without it, the order's pickup location or the default location."}}}}}}, "responses": {"201": {"description": "The shipment and the order after it", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"fulfillment": {"$ref": "#/components/schemas/StoreApiShipment"}, "order": {"$ref": "#/components/schemas/StoreApiOrderDetail"}}}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-orders/{uuid}/refunds": {"post": {"summary": "Refund all or part of an order", "tags": ["Store API"], "description": "Needs Refund and cancel orders. amount is minor units; without it, everything still refundable is refunded. An order paid through Stripe is refunded in the seller's Stripe account and may be pending until Stripe confirms it; an order paid outside Stripe has the refund recorded. Returning items to stock is a separate choice: restock_items lists order items and units, or restock: true returns every unit not yet returned. Send an Idempotency-Key so a retry cannot refund twice.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amount": {"type": "integer", "minimum": 1}, "reason": {"type": "string", "maxLength": 500}, "restock": {"type": "boolean", "default": false}, "restock_items": {"type": "array", "items": {"type": "object", "properties": {"item_id": {"type": "integer"}, "quantity": {"type": "integer", "minimum": 0}}, "required": ["item_id", "quantity"]}}}}}}}, "responses": {"201": {"description": "The refund and the order after it", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"refund": {"$ref": "#/components/schemas/StoreApiRefund"}, "order": {"$ref": "#/components/schemas/StoreApiOrderDetail"}}}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-orders/{uuid}/notes": {"post": {"summary": "Add a note to the order's history", "tags": ["Store API"], "description": "Needs Ship and edit orders.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"text": {"type": "string", "minLength": 1, "maxLength": 2000}}, "required": ["text"]}}}}, "responses": {"201": {"description": "The note", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiOrderEvent"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-orders/{uuid}/tags": {"put": {"summary": "Replace the order's tags", "tags": ["Store API"], "description": "Needs Ship and edit orders. Up to 20 tags of up to 60 characters, without commas; repeats that differ only in case are dropped. An empty list removes them.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"tags": {"type": "array", "items": {"type": "string", "maxLength": 60}}}, "required": ["tags"]}}}}, "responses": {"200": {"description": "The saved tags, A to Z", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"tags": {"type": "array", "items": {"type": "string"}}}}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-products": {"get": {"summary": "List the Store's Products with their variants", "tags": ["Store API"], "description": "Needs Manage products. Includes drafts and archived Products. q matches title, description, vendor, category, tags and SKUs.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 200}}, {"name": "sort", "in": "query", "required": false, "schema": {"type": "string", "enum": ["newest", "title", "price_asc", "price_desc"], "default": "newest"}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of Products", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiProduct"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-products/{uuid}": {"get": {"summary": "Read a Product with its variants, prices and stock", "tags": ["Store API"], "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The Product", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiProduct"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-products/{uuid}/variants/{variantUuid}": {"patch": {"summary": "Change a variant's price, compare-at price, SKU or stock on hand", "tags": ["Store API"], "description": "Prices need Manage products; on_hand needs Manage stock and is recorded as a stock count correction. The changes are saved together or not at all. A price, compare-at price or SKU change sends store.product.updated.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "variantUuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"price_amount": {"type": "integer", "minimum": 1}, "compare_at_amount": {"type": "integer", "minimum": 1, "nullable": true}, "sku": {"type": "string", "maxLength": 100, "nullable": true}, "on_hand": {"type": "integer", "minimum": 0}}}}}}, "responses": {"200": {"description": "The Product after the change", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiProduct"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-products/{uuid}/variants/{variantUuid}/adjustments": {"post": {"summary": "Add or remove stock with a reason", "tags": ["Store API"], "description": "Needs Manage stock. The variant must track stock. unit_cost_amount is allowed only for stock received, and moves the weighted-average cost.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "variantUuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"change": {"type": "integer", "description": "Units added (positive) or removed (negative); not zero."}, "reason": {"type": "string", "enum": ["received", "count", "damaged", "lost", "returned", "other"]}, "unit_cost_amount": {"type": "integer", "minimum": 0}, "note": {"type": "string", "maxLength": 500}, "location": {"type": "string", "format": "uuid", "description": "The active stock location the change happened at. Without it, the default location."}}, "required": ["change", "reason"]}}}}, "responses": {"201": {"description": "The stock movement and the variant after it", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"movement": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "type": {"type": "string"}, "quantity_change": {"type": "integer"}, "quantity_after": {"type": "integer"}, "unit_cost_amount": {"type": "integer", "nullable": true}, "note": {"type": "string", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}}}, "variant": {"$ref": "#/components/schemas/StoreApiVariant"}}}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-inventory": {"get": {"summary": "List variants that track stock, with on hand, reserved and available", "tags": ["Store API"], "description": "Needs Manage stock. low_stock=true lists variants whose available stock is at or below their reorder point.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 200}, "description": "Matches the Product title, variant title or SKU."}, {"name": "low_stock", "in": "query", "required": false, "schema": {"type": "boolean"}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of variants", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiInventoryItem"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-returns": {"get": {"summary": "List the Store's returns", "tags": ["Store API"], "description": "Needs See orders. Newest first.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["requested", "approved", "declined", "received", "closed"]}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of returns", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiReturn"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "total", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-returns/{uuid}": {"get": {"summary": "Read a return", "tags": ["Store API"], "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The return", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiReturn"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-webhooks": {"get": {"summary": "List the Store's webhook endpoints", "tags": ["Store webhooks"], "description": "Team admins only. Signing secrets are not returned.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "responses": {"200": {"description": "Endpoints, newest first", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiWebhook"}}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "post": {"summary": "Add a webhook endpoint", "tags": ["Store webhooks"], "description": "Team admins only. The URL must use HTTPS and resolve to public addresses. A Store can have up to 20 endpoints. The response contains the whole signing secret, which is not shown again. Each body is a StoreWebhookEvent.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 120}, "url": {"type": "string", "format": "uri", "maxLength": 2048}, "events": {"type": "array", "items": {"type": "string", "enum": ["store.order.paid", "store.order.fulfilled", "store.order.refunded", "store.order.canceled", "store.product.updated", "store.stock.low", "store.return.requested", "store.order.ready_for_pickup"]}}, "is_active": {"type": "boolean", "default": true}}, "required": ["name", "url", "events"]}}}}, "responses": {"201": {"description": "The endpoint with its secret", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiWebhook"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-webhooks/{uuid}": {"get": {"summary": "Read a webhook endpoint", "tags": ["Store webhooks"], "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The endpoint", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiWebhook"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "patch": {"summary": "Change a webhook endpoint", "tags": ["Store webhooks"], "description": "Turning an endpoint off, or changing its URL or events, cancels the deliveries it has not received.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 120}, "url": {"type": "string", "format": "uri"}, "events": {"type": "array", "items": {"type": "string", "enum": ["store.order.paid", "store.order.fulfilled", "store.order.refunded", "store.order.canceled", "store.product.updated", "store.stock.low", "store.return.requested", "store.order.ready_for_pickup"]}}, "is_active": {"type": "boolean"}}}}}}, "responses": {"200": {"description": "The endpoint", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiWebhook"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "delete": {"summary": "Remove a webhook endpoint", "tags": ["Store webhooks"], "description": "Cancels the deliveries it has not received.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Removed", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"uuid": {"type": "string", "format": "uuid"}, "deleted": {"type": "boolean"}}}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-webhooks/{uuid}/rotate-secret": {"post": {"summary": "Replace an endpoint's signing secret", "tags": ["Store webhooks"], "description": "The new secret signs every delivery from now on, including retries of earlier events.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The endpoint with its new secret", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiWebhook"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-webhooks/{uuid}/deliveries": {"get": {"summary": "List an endpoint's deliveries", "tags": ["Store webhooks"], "description": "Newest first, without payloads. Payloads are kept 30 days after delivery and 90 days when undelivered.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["pending", "delivered", "failed", "canceled"]}}, {"$ref": "#/components/parameters/StorePage"}, {"$ref": "#/components/parameters/StorePerPage"}], "responses": {"200": {"description": "One page of deliveries", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/StoreApiWebhookDelivery"}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "next_page": {"type": "integer", "nullable": true}}, "required": ["data", "page", "per_page", "next_page"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store-webhooks/{uuid}/deliveries/{deliveryId}/retry": {"post": {"summary": "Send a failed delivery again", "tags": ["Store webhooks"], "description": "Its attempts start over with the same event id and payload. The endpoint must be on.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"$ref": "#/components/parameters/StoreIdempotencyKey"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "deliveryId", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "The delivery", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/StoreApiWebhookDelivery"}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/asset-tracker": {"get": {"summary": "List assets in the selected team","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "q","in": "query","required": false,"schema": {"type": "string"}},{"name": "status","in": "query","required": false,"schema": {"type": "string"}},{"name": "category","in": "query","required": false,"schema": {"type": "string"}},{"name": "location","in": "query","required": false,"schema": {"type": "string"}},{"name": "assignee","in": "query","required": false,"schema": {"type": "string"}},{"name": "bookable","in": "query","required": false,"schema": {"type": "string"}},{"name": "overdue","in": "query","required": false,"schema": {"type": "string"}},{"name": "warranty","in": "query","required": false,"schema": {"type": "string"}},{"name": "sort","in": "query","required": false,"schema": {"type": "string"}},{"name": "limit","in": "query","required": false,"schema": {"type": "integer","minimum": 1,"maximum": 200}},{"name": "offset","in": "query","required": false,"schema": {"type": "integer","minimum": 0}}],"responses": {"200": {"description": "List assets in the selected team","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"$ref": "#/components/schemas/AssetTrackerAsset"}},"pagination": {"type": "object","properties": {"next_offset": {"type": "integer","nullable": true}}}}}}}},"default": {"description": "Safe JSON error"}},"description": "Returns pagination.next_offset; null means the end. Warranty filters and purchase sorting apply only to admins."},"post": {"summary": "Create an asset by name","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"201": {"description": "Create an asset by name","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"$ref": "#/components/schemas/AssetTrackerDetail"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"name": {"type": "string","maxLength": 255}},"required": ["name"]}}}},"description": "Requires edit access. Optional details take defaults, including the next asset tag and team currency."}}, "/asset-tracker/options": {"get": {"summary": "Get asset permissions and choices","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Get asset permissions and choices","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"$ref": "#/components/schemas/AssetTrackerOptions"}}}}}},"default": {"description": "Safe JSON error"}}}}, "/asset-tracker/reports": {"get": {"summary": "Report assets by status, category and location","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Report assets by status, category and location","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object","properties": {"summary": {"type": "object"},"groups": {"type": "object"}}}}}}}},"default": {"description": "Safe JSON error"}},"description": "Financial totals and warranty counts are returned only to admins."}}, "/asset-tracker/{uuid}": {"get": {"summary": "Get asset details and history","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Get asset details and history","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"$ref": "#/components/schemas/AssetTrackerDetail"}}}}}},"default": {"description": "Safe JSON error"}}},"patch": {"summary": "Change an asset property","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Change an asset property","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"$ref": "#/components/schemas/AssetTrackerDetail"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"field": {"type": "string","enum": ["name","assetTag","serialNumber","categoryId","manufacturer","model","description","condition","location","purchaseDate","purchasePrice","purchaseCurrency","supplierName","supplierContactId","warrantyExpiresAt","notes","tags"]},"value": {"type": "string"}},"required": ["field","value"]}}}},"description": "Editors change ordinary properties; only admins change purchase, supplier and warranty properties."}}, "/asset-tracker/{uuid}/{action}": {"post": {"summary": "Assign, check out, return or change asset status","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}},{"name": "action","in": "path","required": true,"schema": {"type": "string","enum": ["assign","unassign","checkout","checkin","lifecycle","bookable","remove-attachment"]}}],"responses": {"200": {"description": "Assign, check out, return or change asset status","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"$ref": "#/components/schemas/AssetTrackerDetail"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"holder": {"type": "string","pattern": "^(user|contact):[1-9][0-9]*$"},"dueAt": {"type": "string","format": "date"},"notes": {"type": "string"},"condition": {"type": "string","enum": ["new","excellent","good","fair","poor","damaged"]},"status": {"type": "string","enum": ["available","maintenance","lost","retired"]},"reason": {"type": "string"},"expectedReturnAt": {"type": "string","format": "date"},"enabled": {"type": "boolean"},"overrideBookingConflict": {"type": "boolean"},"file_uuid": {"type": "string","format": "uuid"}}}}}},"description": "Viewers can only check out to themselves and return an asset they hold. Other actions require edit access. Only admins may override booking conflicts. Bookable requires enabled; checkin requires condition; maintenance requires a reason."}}, "/asset-tracker/{uuid}/attachments": {"post": {"summary": "Attach a private asset file","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Attach a private asset file","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"$ref": "#/components/schemas/AssetTrackerDetail"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"multipart/form-data": {"schema": {"type": "object","properties": {"file": {"type": "string","format": "binary"},"primaryImage": {"type": "string","enum": ["0","1"]}},"required": ["file"]}}}},"description": "Requires edit access. JPG, PNG, WebP or PDF up to 10 MB; primary images must be images."}}, "/asset-tracker/files/{fileUuid}": {"get": {"summary": "Download a private asset attachment","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "fileUuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Download a private asset attachment","content": {"application/octet-stream": {"schema": {"type": "string","format": "binary"}}}},"default": {"description": "Safe JSON error"}}}}, "/asset-tracker/categories": {"post": {"summary": "Add an asset category","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Add an asset category","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"$ref": "#/components/schemas/AssetTrackerCategory"}}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"name": {"type": "string","maxLength": 80}},"required": ["name"]}}}}}}, "/asset-tracker/categories/{uuid}": {"patch": {"summary": "Rename an asset category","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Rename an asset category","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"$ref": "#/components/schemas/AssetTrackerCategory"}}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"name": {"type": "string"}},"required": ["name"]}}}}}}, "/asset-tracker/categories/{uuid}/archive": {"post": {"summary": "Archive an asset category","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Archive an asset category","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"$ref": "#/components/schemas/AssetTrackerCategory"}}}}}}},"default": {"description": "Safe JSON error"}},"description": "Requires edit access. Assets retain the archived category."}}, "/asset-tracker/import": {"post": {"summary": "Import assets from a CSV file","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Import assets from a CSV file","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object","properties": {"imported": {"type": "integer"},"errors": {"type": "array","items": {"type": "string"}}}}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"multipart/form-data": {"schema": {"type": "object","properties": {"csv": {"type": "string","format": "binary"},"columnMapping": {"type": "string","description": "JSON object mapping supported CSV fields to zero-based column indices; name is required."}},"required": ["csv","columnMapping"]}}}},"description": "Requires edit access. CSV up to 5 MB. Explicit mappings replace autodetection. Existing tags are skipped; financial columns are imported only by admins."}}, "/asset-tracker/template": {"get": {"summary": "Download an asset import CSV template","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"description": "Requires team edit access. Header-only CSV containing the supported import columns; financial headings appear only for admins.","responses": {"200": {"description": "CSV column headings","content": {"text/csv": {"schema": {"type": "string","format": "binary"}}}},"403": {"description": "Team edit access required"}}}}, "/asset-tracker/export": {"get": {"summary": "Export filtered assets as CSV","tags": ["Asset Tracker"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "q","in": "query","required": false,"schema": {"type": "string"}},{"name": "status","in": "query","required": false,"schema": {"type": "string"}},{"name": "category","in": "query","required": false,"schema": {"type": "string"}},{"name": "location","in": "query","required": false,"schema": {"type": "string"}},{"name": "assignee","in": "query","required": false,"schema": {"type": "string"}},{"name": "bookable","in": "query","required": false,"schema": {"type": "string"}},{"name": "overdue","in": "query","required": false,"schema": {"type": "string"}},{"name": "warranty","in": "query","required": false,"schema": {"type": "string"}},{"name": "sort","in": "query","required": false,"schema": {"type": "string"}}],"responses": {"200": {"description": "Export filtered assets as CSV","content": {"text/csv": {"schema": {"type": "string","format": "binary"}}}},"default": {"description": "Safe JSON error"}},"description": "Purchase and warranty columns are included only for admins."}}, "/appointments": {"get": {"summary": "List appointments in the selected team","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "view","in": "query","schema": {"type": "string","enum": ["schedule","today","upcoming","past","cancelled"]}},{"name": "staff_user_id","in": "query","schema": {"type": "integer"}}],"responses": {"200": {"description": "Appointments; data has set_up, time_zone, view, staff_user_id, items and truncated","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "At most 300 items. Times are ISO 8601 in the booking page zone. Returns 403 unless the account can open the website's Appointments member pages."},"post": {"summary": "Book a service for a customer","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"201": {"description": "The new appointment"},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"service_uuid": {"type": "string","format": "uuid"},"staff_user_id": {"type": "integer"},"start": {"type": "string","format": "date-time"},"customer_name": {"type": "string"},"customer_email": {"type": "string","format": "email"},"customer_phone": {"type": "string"},"internal_notes": {"type": "string"}},"required": ["service_uuid","staff_user_id","start","customer_name","customer_email"]}}}},"description": "Requires edit access. Uses AppointmentService::book(); the time is rechecked under the team lock, a Calendar event and any resource reservation are added, and the customer is emailed. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/options": {"get": {"summary": "Get Appointments services, staff and permissions","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Options","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "Active services with their staff, active staff, the booking page zone and whether the caller is staff or can edit. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/slots": {"get": {"summary": "List available times for a new booking","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "service_uuid","in": "query","schema": {"type": "string","format": "uuid"}},{"name": "staff_user_id","in": "query","required": true,"schema": {"type": "integer"}},{"name": "date","in": "query","schema": {"type": "string","format": "date"}}],"responses": {"200": {"description": "Slots","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "Requires edit access. Calculated by AppointmentService::slotsForDate(). Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/{uuid}": {"get": {"summary": "Get an appointment","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Appointment","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "The customer management token is never returned. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/{uuid}/slots": {"get": {"summary": "List reschedule times with the same staff member","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}},{"name": "date","in": "query","schema": {"type": "string","format": "date"}}],"responses": {"200": {"description": "Slots","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "Requires edit access. The appointment's own Calendar event and resource reservation do not block it. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/{uuid}/notes": {"post": {"summary": "Change internal notes","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Appointment","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"internal_notes": {"type": "string"}},"required": ["internal_notes"]}}}},"description": "Requires edit access. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/{uuid}/status": {"post": {"summary": "Mark a past appointment completed or no-show","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Appointment","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"status": {"type": "string","enum": ["completed","no_show"]}},"required": ["status"]}}}},"description": "Requires edit access and a confirmed appointment that has ended. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/{uuid}/cancel": {"post": {"summary": "Cancel an appointment","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Appointment","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "Requires edit access. Releases the Calendar event and resource reservation and emails the customer. Returns 403 unless the account can open the website's Appointments member pages."}}, "/appointments/{uuid}/reschedule": {"post": {"summary": "Reschedule an appointment with the same staff member","tags": ["Appointments"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Appointment","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"start": {"type": "string","format": "date-time"}},"required": ["start"]}}}},"description": "Requires edit access. The time is rechecked; the Calendar event and resource reservation move with it and the customer is emailed. Returns 403 unless the account can open the website's Appointments member pages."}}, "/resource-booking/options": {"get": {"summary": "Get resource permissions, types and asset choices","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Get resource permissions, types and asset choices","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object","properties": {"can_edit": {"type": "boolean"},"is_admin": {"type": "boolean"},"actor_id": {"type": "integer"},"types": {"type": "array","items": {"type": "object"}},"assets": {"type": "array","items": {"type": "object"}}}}}}}}},"default": {"description": "Safe JSON error"}}}}, "/resource-booking/schedule": {"get": {"summary": "List upcoming resource reservations","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "List upcoming resource reservations","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"type": "object"}}}}}}},"default": {"description": "Safe JSON error"}},"description": "Private title, notes and requester identity are omitted for other members."}}, "/resource-booking/resources/{uuid}/field": {"post": {"summary": "Change one resource detail or booking rule","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Change one resource detail or booking rule","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"field": {"type": "string","enum": ["name","description","location","publicInstructions","resourceTypeId","timeZone","capacity","approvalRequired","bookingIncrementMinutes","minimumLeadMinutes","maximumAdvanceDays","minimumDurationMinutes","maximumDurationMinutes","bufferBeforeMinutes","bufferAfterMinutes","hours.0","hours.1","hours.2","hours.3","hours.4","hours.5","hours.6"]},"value": {"type": "string"}},"required": ["field","value"]}}}},"description": "Requires edit access. Uses the shared text parser for durations and one daily hours range. Blank hours close the day; blank duration limits clear the limit. Linked-asset location is changed in Asset Tracker."}}, "/resource-booking/resources/{uuid}/active": {"post": {"summary": "Archive or restore a resource","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Archive or restore a resource","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"active": {"type": "boolean"}},"required": ["active"]}}}},"description": "Requires edit access. Future bookings must be resolved before archiving."}}, "/resource-booking/resources/{uuid}/blackouts": {"get": {"summary": "List unavailable resource times","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "List unavailable resource times","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"type": "object"}}}}}}},"default": {"description": "Safe JSON error"}},"description": "Requires edit access."},"post": {"summary": "Add unavailable resource time","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Add unavailable resource time","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"starts_at": {"type": "string"},"ends_at": {"type": "string"},"reason": {"type": "string"}},"required": ["starts_at","ends_at","reason"]}}}},"description": "Requires edit access. Local times use the resource zone; overlapping bookings must be moved or cancelled."}}, "/resource-booking/resources/{uuid}/blackouts/{blackoutUuid}": {"delete": {"summary": "Remove unavailable resource time","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}},{"name": "blackoutUuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Remove unavailable resource time","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "object"}}}}}},"default": {"description": "Safe JSON error"}},"description": "Requires edit access. The unavailable time must belong to this resource and selected team."}}, "/resource-booking/types": {"post": {"summary": "Add a resource type","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"}],"responses": {"200": {"description": "Add a resource type","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"type": "object"}}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"name": {"type": "string"}},"required": ["name"]}}}}}}, "/resource-booking/types/{uuid}": {"patch": {"summary": "Rename or archive a resource type","tags": ["Resource Booking"],"parameters": [{"$ref": "#/components/parameters/TeamScope"},{"name": "uuid","in": "path","required": true,"schema": {"type": "string","format": "uuid"}}],"responses": {"200": {"description": "Rename or archive a resource type","content": {"application/json": {"schema": {"type": "object","properties": {"data": {"type": "array","items": {"type": "object"}}}}}}},"default": {"description": "Safe JSON error"}},"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","properties": {"name": {"type": "string"},"active": {"type": "boolean"}},"required": ["name"]}}}}}}, "/resource-booking/resources": { "get": { "summary": "List resources in the selected team", "tags": ["Resource Booking"], "parameters": [{"name": "q", "in": "query", "schema": {"type": "string"}}], "responses": {"200": {"description": "Resources", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object"}}}}}}}, "default": {"description": "Safe JSON error"}} }, "post": { "summary": "Create a standalone resource or link an existing asset", "tags": ["Resource Booking"], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "properties": { "source_type": {"type": "string", "enum": ["standalone", "asset"]}, "asset_uuid": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "description": {"type": "string"}, "location": {"type": "string"}, "public_instructions": {"type": "string"}, "capacity": {"type": "integer", "minimum": 1, "maximum": 10000}, "resource_type_id": {"type": "integer", "minimum": 1, "nullable": true}, "time_zone": {"type": "string"}, "availability": {"type": "object", "description": "Weekly hours keyed by day number 0–6, each with start and end local times."}, "booking_increment_minutes": {"type": "integer", "enum": [5, 10, 15, 30, 60]}, "minimum_lead_minutes": {"type": "integer", "minimum": 0, "maximum": 525600}, "maximum_advance_days": {"type": "integer", "minimum": 1, "maximum": 365}, "minimum_duration_minutes": {"type": "integer", "minimum": 1, "maximum": 10080, "nullable": true}, "maximum_duration_minutes": {"type": "integer", "minimum": 1, "maximum": 10080, "nullable": true}, "buffer_before_minutes": {"type": "integer", "minimum": 0, "maximum": 1440}, "buffer_after_minutes": {"type": "integer", "minimum": 0, "maximum": 1440}, "approval_required": {"type": "boolean"} }, "required": ["source_type"] }}} }, "responses": {"201": {"description": "Created resource"}, "403": {"description": "Team edit access required"}, "default": {"description": "Safe JSON error"}} } }, "/resource-booking/resources/{uuid}": { "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "get": {"summary": "Get a resource", "tags": ["Resource Booking"], "responses": {"200": {"description": "Resource"}, "404": {"description": "Not found"}, "default": {"description": "Safe JSON error"}}}, "patch": { "summary": "Update a resource and its booking rules", "tags": ["Resource Booking"], "requestBody": {"required": true, "content": {"application/json": {"schema": { "type": "object", "properties": { "name": {"type": "string"}, "description": {"type": "string"}, "location": {"type": "string"}, "public_instructions": {"type": "string"}, "capacity": {"type": "integer", "minimum": 1, "maximum": 10000}, "resource_type_id": {"type": "integer", "minimum": 1, "nullable": true}, "time_zone": {"type": "string"}, "availability": {"type": "object", "description": "Weekly hours keyed by day number 0–6, each with start and end local times."}, "booking_increment_minutes": {"type": "integer", "enum": [5, 10, 15, 30, 60]}, "minimum_lead_minutes": {"type": "integer", "minimum": 0, "maximum": 525600}, "maximum_advance_days": {"type": "integer", "minimum": 1, "maximum": 365}, "minimum_duration_minutes": {"type": "integer", "minimum": 1, "maximum": 10080, "nullable": true}, "maximum_duration_minutes": {"type": "integer", "minimum": 1, "maximum": 10080, "nullable": true}, "buffer_before_minutes": {"type": "integer", "minimum": 0, "maximum": 1440}, "buffer_after_minutes": {"type": "integer", "minimum": 0, "maximum": 1440}, "approval_required": {"type": "boolean"} } }}}}, "responses": {"200": {"description": "Updated resource"}, "403": {"description": "Team edit access required"}, "default": {"description": "Safe JSON error"}} } }, "/resource-booking/resources/{uuid}/availability": { "get": { "summary": "List busy times and unavailable periods", "tags": ["Resource Booking"], "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "from", "in": "query", "schema": {"type": "string", "format": "date"}}, {"name": "to", "in": "query", "schema": {"type": "string", "format": "date"}}], "responses": { "200": { "description": "Busy periods, blackouts and linked-asset availability", "content": {"application/json": {"schema": { "type": "object", "properties": {"data": {"type": "object", "properties": { "resource_uuid": {"type": "string", "format": "uuid"}, "time_zone": {"type": "string"}, "from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}, "asset_available": {"type": "boolean"}, "asset_unavailable_reason": {"type": "string", "nullable": true}, "busy": {"type": "array", "items": {"type": "object", "properties": {"startsAt": {"type": "string", "format": "date-time"}, "endsAt": {"type": "string", "format": "date-time"}, "status": {"type": "string"}}}}, "blackouts": {"type": "array", "items": {"type": "object", "properties": {"startsAt": {"type": "string", "format": "date-time"}, "endsAt": {"type": "string", "format": "date-time"}, "reason": {"type": "string"}}}} }, "required": ["resource_uuid", "time_zone", "from", "to", "asset_available", "asset_unavailable_reason", "busy", "blackouts"]}} }}} }, "default": {"description": "Safe JSON error"} } } }, "/resource-booking/resources/{uuid}/bookings": { "post": {"summary": "Request or confirm a resource booking", "tags": ["Resource Booking"], "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"starts_at": {"type": "string", "format": "date-time"}, "ends_at": {"type": "string", "format": "date-time"}, "title": {"type": "string"}, "notes": {"type": "string"}}, "required": ["starts_at", "ends_at"]}}}}, "responses": {"201": {"description": "Created booking"}, "409": {"description": "Resource is unavailable"}, "default": {"description": "Safe JSON error"}}} }, "/resource-booking/bookings": { "get": {"summary": "List resource bookings", "tags": ["Resource Booking"], "parameters": [{"name": "mine", "in": "query", "schema": {"type": "boolean"}}, {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["pending", "approved", "declined", "cancelled", "completed"]}}, {"name": "upcoming", "in": "query", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Bookings; other members' private details are omitted"}, "default": {"description": "Safe JSON error"}}} }, "/resource-booking/bookings/{uuid}": { "get": {"summary": "Get booking details when permitted", "tags": ["Resource Booking"], "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Booking; private fields are omitted from other members"}, "404": {"description": "Not found"}, "default": {"description": "Safe JSON error"}}}, "patch": {"summary": "Change a booking's title, notes, time or resource", "description": "The requester or a team admin can change a pending or approved booking. Send starts_at and ends_at together to move it; they are read in the resource's time zone unless they carry an offset, and are checked like a new booking. resource_uuid moves a single-resource booking to another resource. A moved booking on a resource that needs approval waits for approval again, unless another admin moves an already approved booking.", "tags": ["Resource Booking"], "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "maxLength": 255}, "notes": {"type": "string", "maxLength": 5000}, "starts_at": {"type": "string", "example": "2026-10-02T09:00"}, "ends_at": {"type": "string", "example": "2026-10-02T10:30"}, "resource_uuid": {"type": "string", "format": "uuid"}}}}}}, "responses": {"200": {"description": "Updated booking"}, "409": {"description": "The change was refused, for example a conflict or a booking that can no longer change"}, "default": {"description": "Safe JSON error"}}} }, "/resource-booking/requests": { "get": {"summary": "List pending resource booking requests", "tags": ["Resource Booking"], "responses": {"200": {"description": "Pending requests"}, "403": {"description": "Team admin access required"}, "default": {"description": "Safe JSON error"}}} }, "/resource-booking/bookings/{uuid}/{action}": { "post": {"summary": "Cancel or review a resource booking", "tags": ["Resource Booking"], "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "action", "in": "path", "required": true, "schema": {"type": "string", "enum": ["cancel", "approve", "decline"]}}], "responses": {"200": {"description": "Booking changed"}, "403": {"description": "Team permission required"}, "409": {"description": "Booking action rejected"}, "default": {"description": "Safe JSON error"}}} }, "/resource-booking/reports": { "get": {"summary": "Report approved booking time against configured hours", "tags": ["Resource Booking"], "parameters": [{"name": "from", "in": "query", "schema": {"type": "string", "format": "date"}}, {"name": "to", "in": "query", "schema": {"type": "string", "format": "date"}}], "responses": {"200": {"description": "Utilization by resource"}, "403": {"description": "Team admin access required"}, "default": {"description": "Safe JSON error"}}} }, "/bookings": { "get": { "summary": "List bookings", "tags": [ "Bookings" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "confirmed", "cancelled", "completed" ] } }, { "name": "start_time_gte", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "start_time_lte", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_archived", "in": "query", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "description": "Search attendee name, email, phone or private meeting notes.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of bookings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true } } } } } } } }, "post": { "summary": "Create a booking", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "attendee", "start_time", "duration_minutes" ], "properties": { "attendee": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "timezone": { "type": "string" } } }, "start_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "event_type_uuid": { "type": "string", "format": "uuid" }, "notes": { "type": "string" }, "sms_opt_in": { "type": "boolean" }, "validate_only": { "type": "boolean" }, "send_notifications": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Booking created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "409": { "description": "Booking conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bookings/{uuid}": { "get": { "summary": "Get a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "attendee": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string" }, "timezone": { "type": "string" } } }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "notes": { "type": "string" }, "send_notifications": { "type": "boolean" }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Booking updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } }, "delete": { "summary": "Delete a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/bookings/{uuid}/cancel": { "post": { "summary": "Cancel a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "send_notifications": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Booking cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } } }, "/bookings/{uuid}/confirm": { "post": { "summary": "Confirm a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Booking confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } } }, "/bookings/{uuid}/archive": { "post": { "summary": "Archive a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Booking archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } } } } }, "/bookings/{uuid}/calendar": { "get": { "summary": "Download a booking calendar file", "description": "Returns an ICS calendar file for a booking owned by the authenticated account.", "tags": [ "Bookings" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ICS calendar file", "content": { "text/calendar": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Booking not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/event-types": { "get": { "summary": "List event types", "tags": [ "Event Types" ], "parameters": [ { "name": "include_inactive", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } } } } } } } }, "post": { "summary": "Create an event type", "tags": [ "Event Types" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "duration_minutes" ], "properties": { "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Event type created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventType" } } } } } } } } }, "/event-types/{uuid}": { "patch": { "summary": "Update an event type", "tags": [ "Event Types" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "duration_minutes": { "type": "integer" }, "description": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Event type updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventType" } } } } } } } }, "delete": { "summary": "Delete an event type", "tags": [ "Event Types" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event type deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/availability": { "get": { "summary": "List availability windows", "tags": [ "Availability" ], "responses": { "200": { "description": "List of availability windows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Availability" } } } } } } } } }, "post": { "summary": "Add availability window", "tags": [ "Availability" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "day_of_week", "start_time", "end_time" ], "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "start_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } } } } } }, "responses": { "201": { "description": "Availability window created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Availability" } } } } } } } } }, "/availability/slots": { "get": { "summary": "Get available time slots", "tags": [ "Availability" ], "parameters": [ { "name": "date", "in": "query", "required": true, "description": "A calendar day in `timezone`.", "schema": { "type": "string", "format": "date" } }, { "name": "duration_minutes", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "timezone", "in": "query", "required": false, "description": "IANA time zone the day and `display` are in, e.g. America/Los_Angeles. Defaults to the account's time zone. Availability hours are always read in the account's time zone.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of available time slots", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "Start in the server's storage time zone, Y-m-d H:i:s. Accepted as start_time when creating or rescheduling a meeting." }, "end": { "type": "string", "description": "End in the server's storage time zone, Y-m-d H:i:s." }, "start_iso": { "type": "string", "format": "date-time", "description": "Start with its UTC offset, in `timezone`." }, "end_iso": { "type": "string", "format": "date-time", "description": "End with its UTC offset, in `timezone`." }, "display": { "type": "string", "description": "Start time in `timezone`, e.g. 9:00 AM." }, "timezone": { "type": "string", "description": "The IANA time zone of start_iso, end_iso and display." }, "available": { "type": "boolean" } } } } } } } } } } } }, "/availability/clear": { "post": { "summary": "Clear all availability", "tags": [ "Availability" ], "responses": { "200": { "description": "Availability cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "cleared": { "type": "boolean" } } } } } } } } }, "/availability/{uuid}": { "delete": { "summary": "Delete availability window", "tags": [ "Availability" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Availability window deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/users/me": { "get": { "summary": "Get current user", "tags": [ "Users" ], "responses": { "200": { "description": "Current user information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } } } } } } }, "/users/me/email-verification/code/start": { "post": { "summary": "Email a code that confirms the account's address from the app", "description": "The app session only (403 forbidden for an API key or another session). Emails a code to the account's current address, which the server reads, and returns the request with that address. 422 already_confirmed; otherwise the limits and failures of auth/email/start.", "tags": [ "Users" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/MobileEmailCodeRequest" }, { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } ] } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/me/email-verification/code": { "post": { "summary": "Confirm the account's address with the emailed code", "description": "The app session that asked only. The answers of auth/email/code; a request of another session, a sign-in request or a code for another account is 422 code_used_up. Returns confirmed with the account, or the sign-in check held for this session.", "tags": [ "Users" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/EmailConfirmed" }, { "$ref": "#/components/schemas/MobileSignInCheckRequired" } ] } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sign_in_request": { "type": "string" }, "code": { "type": "string" }, "push_token": { "type": "string", "description": "This phone's notification registration, kept through Remove." } }, "required": [ "sign_in_request", "code" ] } } } } } }, "/users/me/email-verification/check": { "post": { "summary": "Read the sign-in check held while confirming", "description": "The app session that asked only, which is left out of apps, as is its phone's registration from devices. 410 sign_in_check_expired otherwise. Limited by login_ip.", "tags": [ "Users" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSignInCheckDetails" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sign_in_check_token": { "type": "string" } }, "required": [ "sign_in_check_token" ] } } } } } }, "/users/me/email-verification/check/finish": { "post": { "summary": "Keep or remove what is set up, and confirm the address", "description": "The app session that asked only. keep confirms the address; remove removes what the check lists and signs out every other session, keeps this session and its phone's registration, and re-binds the session to the new credentials. 410 sign_in_check_expired, 422 invalid_request, 500 sign_in_check_failed.", "tags": [ "Users" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailConfirmed" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sign_in_check_token": { "type": "string" }, "choice": { "type": "string", "description": "keep or remove" } }, "required": [ "sign_in_check_token", "choice" ] } } } } } }, "/users/me/profile": { "get": { "summary": "Get the current account profile", "tags": [ "Users" ], "responses": { "200": { "description": "Current account profile and supported time zones", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileProfile" }, "timezone_choices": { "type": "array", "maxItems": 600, "items": { "type": "string" } } } } } } } } }, "patch": { "summary": "Update safe account profile fields", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255 }, "bio": { "type": "string", "maxLength": 1000 }, "avatar_image_uuid": { "type": "string", "format": "uuid", "nullable": true }, "timezone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated account profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileProfile" }, "timezone_choices": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/coaching": { "parameters": [{ "$ref": "#/components/parameters/TeamScope" }], "get": { "summary": "Coaching overview", "description": "Needs attention, what waits for the coach, today and tomorrow, and coaching ending soon. Each item has the website path the app opens. Site administrators only while Coaching is a preview.", "tags": ["Coaching"], "responses": { "200": { "description": "Coaching overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/clients": { "parameters": [{ "$ref": "#/components/parameters/TeamScope" }], "get": { "summary": "List coaching clients", "description": "The clients the actor may open, 30 a page, with filters, counts and pagination.next_offset.", "tags": ["Coaching"], "parameters": [{ "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "A Clients tab; active by default" }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Search by name" }, { "in": "query", "name": "offset", "schema": { "type": "integer" }, "description": "Where the page starts" }], "responses": { "200": { "description": "List coaching clients", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/clients/{uuid}": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "get": { "summary": "Read a client's coaching", "description": "Goals, actions, habits, sessions, attention and unread messages, for the coaches named on it and the team's admins.", "tags": ["Coaching"], "responses": { "200": { "description": "Read a client's coaching", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/clients/{uuid}/messages": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "get": { "summary": "Read coaching messages", "description": "Oldest first, after a message id when given; marks them read. Only the coaches named on the coaching.", "tags": ["Coaching"], "parameters": [{ "in": "query", "name": "after", "schema": { "type": "integer" }, "description": "A message id" }], "responses": { "200": { "description": "Read coaching messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Send a coaching message", "description": "Sends a message as the coach; the client is emailed after 15 minutes unread.", "tags": ["Coaching"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {"body": { "type": "string", "maxLength": 10000 }} } } } }, "responses": { "201": { "description": "Send a coaching message", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/sessions/{uuid}": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "get": { "summary": "Read a coaching session", "description": "When and where, prep, private notes (null for a reader who is not named on the coaching), the recap and the actions agreed.", "tags": ["Coaching"], "responses": { "200": { "description": "Read a coaching session", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/sessions/{uuid}/text": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "post": { "summary": "Save session notes or recap", "description": "Saves private_notes or recap as typed. A version older than the saved one is refused with 422.", "tags": ["Coaching"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {"field": { "type": "string", "enum": ["private_notes", "recap"] }, "text": { "type": "string" }, "version": { "type": "integer" }} } } } }, "responses": { "200": { "description": "Save session notes or recap", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/sessions/{uuid}/mark": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "post": { "summary": "Mark a session held or a no-show", "description": "Once it has started.", "tags": ["Coaching"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {"status": { "type": "string", "enum": ["held", "no_show"] }} } } } }, "responses": { "200": { "description": "Mark a session held or a no-show", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/sessions/{uuid}/send-recap": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "post": { "summary": "Send a session recap", "description": "Shares the recap with the client and emails them that it is ready.", "tags": ["Coaching"], "responses": { "200": { "description": "Send a session recap", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coaching/sessions/{uuid}/actions": { "parameters": [{ "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/TeamScope" }], "post": { "summary": "Add an action agreed in a session", "description": "An action for the client or the team, with an optional due date.", "tags": ["Coaching"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {"title": { "type": "string" }, "owner": { "type": "string", "enum": ["client", "team"] }, "due": { "type": "string", "format": "date" }} } } } }, "responses": { "200": { "description": "Add an action agreed in a session", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "403": { "description": "Coaching is not available to the actor here" }, "404": { "description": "Not found, or not one the actor may open" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching": { "get": { "summary": "List my coaching", "description": "Each Client Portal this account is a client of that has started coaching, with how much waits. No team header is read.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }], "get": { "summary": "Read my Coaching page", "description": "What to do now, goals, actions, habits, check-ins, sessions and the rest, as the portal shows them.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}/check-ins/{uuid}": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }], "get": { "summary": "Read a check-in", "description": "Its questions while it is open, with what was kept, or the answers sent.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}/messages": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }], "get": { "summary": "Read messages with my coach", "description": "Oldest first; reading them marks them read.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}/sessions": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }], "get": { "summary": "List my sessions", "description": "Upcoming and past, and whether a session can be booked.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}/sessions/{uuid}": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }], "get": { "summary": "Read a session", "description": "Its time and place, a join address for Zoom, Google Meet or another link (not Video Chat), prep, recap, actions agreed and rating.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}/settings": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }], "get": { "summary": "Read my Coaching settings", "description": "The daily email time, each reminder's choice, and which come to the app instead of email.", "tags": ["My coaching"], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/my-coaching/{portal}/actions": { "parameters": [{ "in": "path", "name": "portal", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,80}$" }, "description": "The portal's address" }], "post": { "summary": "Act on my coaching", "description": "One of the portal's own actions, by name, with its input. Returns the message, the portal page it leads to and, for a saved text, its version.", "tags": ["My coaching"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {"action": { "type": "string" }, "view": { "type": "string" }, "input": { "type": "object" }}, "required": ["action"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} }, "required": ["data"] } } } }, "404": { "description": "Not this account's coaching, or not open to it yet" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues": { "parameters": [ { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "get": { "summary": "List issues in the selected team", "description": "Returns up to 100 issues per page. The project filter takes a project UUID; status accepts a key configured in the selected team.", "tags": ["Issues"], "parameters": [ { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 240 } }, { "in": "query", "name": "status", "schema": { "type": "string" } }, { "in": "query", "name": "priority", "schema": { "type": "string", "enum": ["none", "urgent", "high", "medium", "low"] } }, { "in": "query", "name": "project", "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "assignee", "description": "Team member user ID", "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "Issue page", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "page": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": ["data", "page", "has_more"] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an issue in the selected team", "description": "Requires team edit access. Issues created with an API key enter the team's Triage queue with source api; issues created from the Magpie app do not.", "tags": ["Issues"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["title"], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description_markdown": { "type": "string", "maxLength": 100000 }, "project_uuid": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Created issue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Issue" } }, "required": ["data"] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/trash": { "parameters": [ { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "get": { "summary": "List issues in Trash", "description": "Returns up to 100 issues per page that are still within the 30-day recovery window. Requires team view access.", "tags": ["Issues"], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "Trash page", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "title": { "type": "string" }, "deleted_at": { "type": "string", "format": "date-time" }, "restore_until": { "type": "string", "format": "date-time" } }, "required": ["uuid", "identifier", "title", "deleted_at", "restore_until"] } }, "page": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": ["data", "page", "has_more"] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{uuid}": { "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "get": { "summary": "Read one issue in the selected team", "tags": ["Issues"], "responses": { "200": { "description": "Issue detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Issue" } }, "required": ["data"] } } } }, "404": { "description": "Issue not found in this team" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move an issue to Trash", "description": "Requires team edit access. The issue can be restored for 30 days.", "tags": ["Issues"], "responses": { "200": { "description": "Issue moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "deleted_at": { "type": "string", "format": "date-time" }, "restore_until": { "type": "string", "format": "date-time" } }, "required": ["uuid", "identifier", "deleted_at", "restore_until"] } }, "required": ["data"] } } } }, "404": { "description": "Issue not found in this team" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update one issue", "description": "Requires team edit access. Send one or more supported fields; use null to clear assignee_user_id or due_date.", "tags": ["Issues"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "description_markdown": { "type": "string", "maxLength": 100000 }, "status": { "type": "string" }, "priority": { "type": "string", "enum": ["none", "urgent", "high", "medium", "low"] }, "assignee_user_id": { "type": "integer", "minimum": 1, "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated issue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Issue" } }, "required": ["data"] } } } }, "404": { "description": "Issue not found in this team" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/options": { "parameters": [ { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "get": { "summary": "List issue property choices in the selected team", "description": "Returns the team's statuses in workflow order, the supported priorities, the members an issue can be assigned to, the team's projects, and whether the actor can edit issues. Requires team view access.", "tags": ["Issues"], "responses": { "200": { "description": "Issue options", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "can_edit": { "type": "boolean" }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": ["backlog", "unstarted", "started", "completed", "cancelled"] } }, "required": ["key", "name", "category"] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": ["key", "label"] } }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": ["id", "name"] } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": ["uuid", "name"] } } }, "required": ["can_edit", "statuses", "priorities", "assignees", "projects"] } }, "required": ["data"] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{uuid}/comments": { "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "get": { "summary": "List an issue's comments", "description": "Returns up to 500 comments, oldest first. Requires team view access.", "tags": ["Issues"], "responses": { "200": { "description": "Comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IssueComment" } } }, "required": ["data"] } } } }, "404": { "description": "Issue not found in this team" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Comment on an issue", "description": "Requires team view access. Returns the issue's comments including the new one.", "tags": ["Issues"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["body_markdown"], "additionalProperties": false, "properties": { "body_markdown": { "type": "string", "minLength": 1, "maxLength": 20000 } } } } } }, "responses": { "201": { "description": "Comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IssueComment" } } }, "required": ["data"] } } } }, "404": { "description": "Issue not found in this team" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{uuid}/restore": { "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can edit.", "schema": { "type": "integer", "minimum": 1 } } ], "post": { "summary": "Restore an issue from Trash", "description": "Requires team edit access and an issue that is less than 30 days into its recovery window. Send no request fields.", "tags": ["Issues"], "responses": { "200": { "description": "Restored issue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Issue" } }, "required": ["data"] } } } }, "404": { "description": "Issue not found in this team" }, "410": { "description": "Issue recovery window expired" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trash": { "parameters": [ { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "get": { "summary": "List the selected team's Trash", "description": "Returns up to 50 entries per page, newest first: what was moved to Trash in the last 30 days in the areas the actor can use, and the actor's own Screen Recorder recordings. Each entry says whether the actor can restore it or delete it forever; areas counts the entries in each area.", "tags": ["Trash"], "parameters": [ { "in": "query", "name": "area", "description": "Only this area's entries, such as notes, documents or issues.", "schema": { "type": "string" } }, { "in": "query", "name": "q", "description": "Only entries whose title contains this text.", "schema": { "type": "string", "maxLength": 240 } }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "Trash page", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The Trash entry's uuid." }, "title": { "type": "string" }, "label": { "type": "string", "description": "What it is, such as Document or Issue ENG-142." }, "area": { "type": "string" }, "detail": { "type": "string", "nullable": true, "description": "A second fact, such as a website's address." }, "moved_by_name": { "type": "string", "nullable": true, "description": "Null when that person's account was deleted." }, "moved_by_you": { "type": "boolean" }, "moved_at": { "type": "string", "format": "date-time" }, "restore_until": { "type": "string", "format": "date-time" }, "can_restore": { "type": "boolean" }, "can_delete_forever": { "type": "boolean" } }, "required": ["uuid", "title", "label", "area", "detail", "moved_by_name", "moved_by_you", "moved_at", "restore_until", "can_restore", "can_delete_forever"] } }, "areas": { "type": "array", "items": { "type": "object", "properties": { "area": { "type": "string" }, "name": { "type": "string" }, "plural": { "type": "string" }, "count": { "type": "integer" } }, "required": ["area", "name", "plural", "count"] } }, "page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": ["data", "areas", "page", "total", "has_more"] } } } }, "422": { "description": "An unknown filter, area or page" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trash/{uuid}/restore": { "parameters": [ { "in": "path", "name": "uuid", "required": true, "description": "The Trash entry's uuid, from GET /trash; not the uuid of the thing in it.", "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "post": { "summary": "Restore something from Trash", "description": "Brings it back as it was, with its links, sharing and collaborators. Requires the right to move it to Trash in its area now. Send no request fields.", "tags": ["Trash"], "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "record": { "type": "object", "properties": { "type": { "type": "string" }, "uuid": { "type": "string", "format": "uuid" }, "area": { "type": "string" } }, "required": ["type", "uuid", "area"] }, "message": { "type": "string" } }, "required": ["uuid", "record", "message"] } }, "required": ["data"] } } } }, "403": { "description": "The actor cannot restore it" }, "404": { "description": "Not in the selected team's Trash" }, "409": { "description": "Restoring it would go over a plan limit (error code plan_limit) or it needs something else that is in Trash (error code in_use)" }, "410": { "description": "Its 30 days are over (error code restore_window_expired)" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trash/{uuid}": { "parameters": [ { "in": "path", "name": "uuid", "required": true, "description": "The Trash entry's uuid, from GET /trash; not the uuid of the thing in it.", "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-Magpie-Team-Id", "description": "Select a team the authenticated actor can view.", "schema": { "type": "integer", "minimum": 1 } } ], "delete": { "summary": "Delete something in Trash forever", "description": "Removes it and its files at once; it cannot be restored. Team admins can delete anything in their team's Trash, and other members what they made. Send no request fields.", "tags": ["Trash"], "responses": { "200": { "description": "Deleted forever", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": ["deleted"] } } } }, "403": { "description": "The actor cannot delete it forever" }, "404": { "description": "Not in the selected team's Trash" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "summary": "List webhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "post": { "summary": "Create a webhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "booking.created", "booking.updated", "booking.rescheduled", "booking.cancelled", "booking.confirmed", "booking.deleted", "booking.archived", "event-type.created", "event-type.updated", "event-type.deleted", "proposal.sent", "proposal.viewed", "proposal.accepted", "proposal.declined", "webinar.registered", "webinar.attended", "webinar.ended", "course.enrolled", "course.completed", "course.access_ended" ] } }, "secret": { "type": "string" } } } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "/webhooks/{id}": { "patch": { "summary": "Update a webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "rotate_secret": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } } } }, "delete": { "summary": "Delete a webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/tools": { "get": { "summary": "Canonical tools and supported creation permissions", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/invoices": { "get": { "summary": "List selected-team invoices for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "due", "overdue", "paid", "void" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileInvoice" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a draft invoice for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileInvoiceWrite" } } } }, "responses": { "201": { "description": "Draft invoice created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "422": { "description": "Invoice validation or plan limit error" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/options": { "get": { "summary": "Read invoice editor options for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Contacts, currencies and invoice defaults", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoiceOptions" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/settings": { "get": { "summary": "Read invoice settings for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Current invoice numbering, defaults and business details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoiceSettings" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update one invoice settings section for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileInvoiceSettingsWrite" } } } }, "responses": { "200": { "description": "Updated invoice settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoiceSettings" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "422": { "description": "Invoice settings validation error" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/settings/logo": { "patch": { "summary": "Update the invoice logo from the account image library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileInvoiceLogoWrite" } } } }, "responses": { "200": { "description": "Updated invoice settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoiceSettings" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "422": { "description": "Invoice logo validation error" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{uuid}/pdf": { "get": { "summary": "Download an authorized invoice PDF", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private invoice PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Invoice not found in this workspace" }, "500": { "description": "Safe PDF generation error" } } } }, "/invoices/{uuid}/send-options": { "get": { "summary": "Read authorized invoice recipient options", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved contact email addresses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoiceSendOptions" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "404": { "description": "Invoice not found in this workspace" }, "422": { "description": "Invoice contact is unavailable" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{uuid}": { "get": { "summary": "Read a selected-team invoice and line items for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit a draft invoice for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileInvoiceWrite" } } } }, "responses": { "200": { "description": "Draft invoice updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": [ "data" ] } } } }, "403": { "description": "Team edit access required" }, "404": { "description": "Invoice not found in this workspace" }, "422": { "description": "Invoice validation or state error" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/tax-rates": { "get": { "summary": "List the selected team's tax rates, archived ones last", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }], "responses": { "200": { "description": "Tax rates and the one new items start with", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } }, "default_tax_rate_uuid": { "type": "string", "nullable": true } } } } } } } }, "post": { "summary": "Add a tax rate with one component", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "rate_percent": { "type": "string", "description": "0 to 100, up to four decimal places." } }, "required": ["name", "rate_percent"] } } } }, "responses": { "201": { "description": "The updated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } }, "default_tax_rate_uuid": { "type": "string", "nullable": true } } } } } }, "403": { "description": "View-only access" }, "422": { "description": "Missing name, duplicate name or invalid percentage" } } } }, "/invoices/tax-rates/{uuid}": { "patch": { "summary": "Rename, archive or restore a tax rate, or make it the rate for new items", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "applies_by_default": { "type": "boolean" }, "active": { "type": "boolean" } }, "minProperties": 1 } } } }, "responses": { "200": { "description": "The updated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } }, "default_tax_rate_uuid": { "type": "string", "nullable": true } } } } } }, "403": { "description": "View-only access" }, "422": { "description": "Rejected" } } } }, "/invoices/tax-rates/{uuid}/components": { "post": { "summary": "Add a component to a tax rate", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "rate_percent": { "type": "string", "description": "0 to 100, up to four decimal places." } }, "required": ["name", "rate_percent"] } } } }, "responses": { "200": { "description": "The updated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } }, "default_tax_rate_uuid": { "type": "string", "nullable": true } } } } } }, "403": { "description": "View-only access" }, "422": { "description": "Rejected" } } } }, "/invoices/tax-rates/{uuid}/components/{componentUuid}": { "patch": { "summary": "Change a component", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "componentUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "rate_percent": { "type": "string" }, "is_compound": { "type": "boolean" }, "is_recoverable": { "type": "boolean" } }, "minProperties": 1 } } } }, "responses": { "200": { "description": "The updated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } }, "default_tax_rate_uuid": { "type": "string", "nullable": true } } } } } }, "403": { "description": "View-only access" }, "422": { "description": "Rejected" } } }, "delete": { "summary": "Remove a component; a rate keeps at least one", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "componentUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "The updated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTaxRate" } }, "default_tax_rate_uuid": { "type": "string", "nullable": true } } } } } }, "403": { "description": "View-only access" }, "422": { "description": "The rate's only component" } } } }, "/invoices/{uuid}/payments": { "get": { "summary": "List payments and refunds recorded for an invoice", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Payments, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileInvoicePayment" } } } } } } } } }, "post": { "summary": "Record a payment or refund on an issued invoice", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["payment", "refund"], "default": "payment" }, "amount": { "type": "string", "description": "Decimal amount in the invoice currency, such as \"120.50\"." }, "received_on": { "type": "string", "format": "date" }, "method": { "type": "string", "enum": ["bank_transfer", "card", "cash", "cheque", "online", "other"] }, "reference": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 2000 } }, "required": ["amount", "received_on"] } } } }, "responses": { "201": { "description": "The invoice with its updated balance and payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": ["data"] } } } }, "403": { "description": "View-only access" }, "422": { "description": "Rejected: more than the balance due, more than was paid, a future date, or an invoice that is not issued" } } } }, "/invoices/{uuid}/payments/{paymentUuid}": { "patch": { "summary": "Change one recorded payment or refund", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount in the invoice currency, such as \"120.50\"." }, "received_on": { "type": "string", "format": "date" }, "method": { "type": "string", "enum": ["bank_transfer", "card", "cash", "cheque", "online", "other"] }, "reference": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 2000 } }, "minProperties": 1 } } } }, "responses": { "200": { "description": "The invoice with its updated balance and payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": ["data"] } } } }, "403": { "description": "View-only access" }, "422": { "description": "Rejected: more than the balance due, more than was paid, a future date, or an invoice that is not issued" } } }, "delete": { "summary": "Remove a payment or refund recorded by mistake", "parameters": [{ "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "The invoice with its updated balance and payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": ["data"] } } } }, "403": { "description": "View-only access" }, "422": { "description": "Removing it would leave refunds larger than payments" } } } }, "/invoices/{uuid}/{action}": { "post": { "summary": "Apply an authorized invoice lifecycle action", "description": "mark-paid records one payment for the balance due, dated today. mark-unpaid removes every recorded payment and refund.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "mark-paid", "mark-unpaid", "void", "reopen", "duplicate", "delete", "send" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "format": "email" } }, "request_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Updated invoice, send result or deletion result", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileInvoice" } }, "required": [ "data" ] }, { "$ref": "#/components/schemas/MobileInvoiceSendResult" }, { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } ] } } } }, "403": { "description": "Team edit access required" }, "404": { "description": "Invoice or action not found" }, "422": { "description": "Invoice state does not allow the action" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store": { "get": { "summary": "Read the selected team's Store management overview", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Store overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreOverview" } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Store not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/publication": { "post": { "summary": "Publish or unpublish the selected team's Store", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated Store overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreOverview" } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin required" }, "422": { "description": "Store is not ready to publish" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/payments": { "get": { "summary": "Read the selected team's Store payment setup", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Payment setup state", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStorePayments" } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin required" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/payments/onboarding": { "post": { "summary": "Start or resume Stripe Connect onboarding for the selected team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Hosted Stripe onboarding URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin required" }, "422": { "description": "Country or Stripe setup validation failed" }, "503": { "description": "Payments are not configured" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/shipping": { "get": { "summary": "Read the selected team's Store shipping zones", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Shipping zones", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreShippingData" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a Store shipping zone", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "countries", "methodName", "type" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "countries": { "type": "string", "maxLength": 500 }, "methodName": { "type": "string", "maxLength": 150 }, "type": { "type": "string", "enum": [ "flat", "free", "free_over" ] }, "amount": { "type": "string", "maxLength": 50 }, "thresholdAmount": { "type": "string", "maxLength": 50 }, "deliveryDescription": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Created shipping zone and current zone list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreShippingData" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/shipping/{zoneId}": { "patch": { "summary": "Update a Store shipping zone and method", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "zoneId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method_id", "name", "countries", "methodName", "type" ], "properties": { "method_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 150 }, "countries": { "type": "string", "maxLength": 500 }, "methodName": { "type": "string", "maxLength": 150 }, "type": { "type": "string", "enum": [ "flat", "free", "free_over" ] }, "amount": { "type": "string", "maxLength": 50 }, "thresholdAmount": { "type": "string", "maxLength": 50 }, "deliveryDescription": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Updated shipping zone list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreShippingData" } }, "required": [ "data" ] } } } }, "422": { "description": "Shipping validation error" }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/settings": { "get": { "summary": "Read the selected team's Store settings", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Store settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreSettings" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update one editable Store setting", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "enum": [ "name", "slug", "description", "contactEmail", "currency", "originCountry", "shippingPolicy", "returnsPolicy" ] }, "value": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated Store settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreSettings" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/collections": { "get": { "summary": "Read the selected team's Store collections", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Store collections and product choices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreCollectionsData" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a Store collection", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "published", "products" ], "properties": { "title": { "type": "string", "maxLength": 150 }, "slug": { "type": "string", "maxLength": 150 }, "description": { "type": "string", "maxLength": 2000 }, "published": { "type": "boolean" }, "products": { "type": "array", "maxItems": 200, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "201": { "description": "Created collection and current collection data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreCollectionsData" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/collections/{uuid}": { "get": { "summary": "Read a selected team's Store collection", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Store collection detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreCollectionDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a Store collection", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "published", "products" ], "properties": { "title": { "type": "string", "maxLength": 150 }, "slug": { "type": "string", "maxLength": 150 }, "description": { "type": "string", "maxLength": 2000 }, "published": { "type": "boolean" }, "products": { "type": "array", "maxItems": 200, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Updated collection and current collection data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreCollectionsData" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/files": { "get": { "summary": "Browse the selected admin's Store digital-file library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Digital-file library", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileStoreDigitalFile" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Upload one private Store digital file", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "PDF or ZIP, up to 25MB." } } } } } }, "responses": { "201": { "description": "Uploaded file", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/MobileStoreDigitalFile" } }, "required": [ "file" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/products": { "get": { "summary": "List selected team's Store products for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "featured", "newest", "price_asc", "price_desc" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Product summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileStoreProduct" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a draft Store product", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "product_type" ], "properties": { "title": { "type": "string", "maxLength": 300 }, "description": { "type": "string", "maxLength": 5000 }, "price": { "type": "string", "maxLength": 50 }, "sku": { "type": "string", "maxLength": 100 }, "product_type": { "type": "string", "enum": [ "physical", "digital" ] }, "file_uuid": { "type": "string", "format": "uuid", "description": "Optional. A digital product stays a draft until it has a file." } } } } } }, "responses": { "201": { "description": "Created draft product", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreProductDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/products/{uuid}": { "get": { "summary": "Read a selected team's Store product for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreProductDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update an authorized Store product field or status", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "field": { "type": "string", "enum": [ "title", "description", "slug", "requiresShipping", "isFeatured", "price", "compareAt", "unitCost", "sku", "inventoryQuantity", "trackInventory", "isActive" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "integer" } ] }, "variant_uuid": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "attach_image", "remove_image", "attach_file", "remove_file", "save_options" ] }, "image_uuid": { "type": "string", "format": "uuid" }, "image_id": { "type": "integer", "minimum": 1 }, "file_uuid": { "type": "string", "format": "uuid" }, "options": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/MobileStoreProductOption" } } } } } } }, "responses": { "200": { "description": "Updated product detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreProductDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/orders": { "get": { "summary": "List selected team's Store order summaries for mobile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "payment", "in": "query", "schema": { "type": "string", "enum": [ "pending", "paid", "failed", "canceled", "partially_refunded", "refunded" ] } }, { "name": "fulfillment", "in": "query", "schema": { "type": "string", "enum": [ "unfulfilled", "fulfilled", "canceled" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "oldest" ], "default": "newest" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Order summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileStoreOrder" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/orders/{uuid}": { "get": { "summary": "Read a selected team's Store order summary and line items", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreOrder" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/orders/{uuid}/fulfill": { "post": { "summary": "Mark a paid Store order fulfilled", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrier": { "type": "string", "maxLength": 150 }, "tracking_number": { "type": "string", "maxLength": 200 }, "tracking_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Optional HTTPS tracking URL." } } } } } }, "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreOrder" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/orders/{uuid}/cancel": { "post": { "summary": "Cancel a pending Store order", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreOrder" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/orders/{uuid}/refund": { "post": { "summary": "Refund a Store order", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 }, "restock": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileStoreOrder" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/stock-counts/variants": { "get": { "summary": "Variants a stock count can include (needs Manage stock)", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 200 }, "description": "Product or variant name, SKU or barcode." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of countable variants", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileStockCountVariant" } }, "total": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "total", "next_offset" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/stock-counts/lookup": { "get": { "summary": "Variants whose barcode or SKU is exactly a code (needs Manage stock)", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "code", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Up to 20 matching variants, including ones that cannot be counted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileStockCountVariant" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/stock-counts": { "post": { "summary": "Submit a stock count as count movements (needs Manage stock)", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "idempotency_key", "lines" ], "properties": { "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$", "description": "The same key and body return the first result without counting again." }, "note": { "type": "string", "maxLength": 500, "nullable": true }, "lines": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "additionalProperties": false, "required": [ "variant_uuid", "counted_quantity" ], "properties": { "variant_uuid": { "type": "string", "format": "uuid" }, "counted_quantity": { "type": "integer", "minimum": 0, "maximum": 1000000 } } } } } } } } }, "responses": { "201": { "description": "The count was applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileStockCountResponse" } } } }, "200": { "description": "The same key and body were already applied; the first result, with replayed true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileStockCountResponse" } } } }, "409": { "description": "The key was already used with a different body (stock_count_key_reused)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A line was refused (stock_count_rejected); nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/store/sell": {"get": {"summary": "Locations, open registers and whether cards can be taken (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "responses": {"200": {"description": "Sell setup", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/catalog": {"get": {"summary": "Items the Sell screen offers (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "query", "name": "q", "schema": {"type": "string", "maxLength": 200}}, {"in": "query", "name": "limit", "schema": {"type": "integer", "minimum": 1, "maximum": 500, "default": 200}}, {"in": "query", "name": "offset", "schema": {"type": "integer", "minimum": 0, "default": 0}}], "responses": {"200": {"description": "A page of sellable variants", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "total", "next_offset"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/MobileSellItem"}}, "total": {"type": "integer"}, "next_offset": {"type": "integer", "nullable": true}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/lookup": {"get": {"summary": "Sellable variants whose barcode or SKU is exactly a code (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "query", "name": "code", "required": true, "schema": {"type": "string", "minLength": 1, "maxLength": 64}}], "responses": {"200": {"description": "Up to 20 matching variants", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/MobileSellItem"}}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/quote": {"post": {"summary": "The Store's prices and discounts for a cart (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["lines"], "properties": {"lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "required": ["variant_uuid", "quantity"], "properties": {"variant_uuid": {"type": "string", "format": "uuid"}, "quantity": {"type": "integer", "minimum": 1, "maximum": 10000}}}}, "discount_code": {"type": "string", "maxLength": 40}}}}}}, "responses": {"200": {"description": "The cart priced by the server", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/registers": {"post": {"summary": "Open a location's register with its starting cash (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["location_uuid"], "properties": {"location_uuid": {"type": "string", "format": "uuid"}, "opening_float": {"type": "string", "description": "An amount in the Store's currency, such as 50.00."}}}}}}, "responses": {"201": {"description": "The open register", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellRegister"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/registers/{uuid}": {"get": {"summary": "A register's sales and expected cash (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The register", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellRegister"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/registers/{uuid}/close": {"post": {"summary": "Close a register with the cash counted (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["counted_cash"], "properties": {"counted_cash": {"type": "string"}, "note": {"type": "string", "maxLength": 1000}}}}}}, "responses": {"200": {"description": "The closed register with the difference", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellRegister"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/sales": {"post": {"summary": "Record a cash sale or start a card sale (needs Sell in person)", "description": "Cash is recorded paid at once. Card reserves the sale and creates a card_present PaymentIntent in the seller's connected account; its client secret is returned for the app's card reader. The same idempotency_key and items return the first sale.", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["idempotency_key", "register_uuid", "payment", "lines"], "properties": {"idempotency_key": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$"}, "register_uuid": {"type": "string", "format": "uuid"}, "payment": {"type": "string", "enum": ["cash", "card"]}, "lines": {"type": "array", "minItems": 1, "maxItems": 200, "items": {"type": "object", "required": ["variant_uuid", "quantity"], "properties": {"variant_uuid": {"type": "string", "format": "uuid"}, "quantity": {"type": "integer", "minimum": 1, "maximum": 10000}}}}, "discount_code": {"type": "string", "maxLength": 40}, "cash_tendered": {"type": "string", "description": "Empty for the exact total."}, "email": {"type": "string", "format": "email"}}}}}}, "responses": {"201": {"description": "The sale", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "replayed"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellSale"}, "payment_intent_client_secret": {"type": "string", "nullable": true}, "replayed": {"type": "boolean"}}}}}}, "409": {"description": "The key was already used for a different sale (sale_key_reused)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/sales/{uuid}": {"get": {"summary": "An in-person sale (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The sale", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellSale"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/sales/{uuid}/confirm": {"post": {"summary": "Confirm a card sale from Stripe's PaymentIntent (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The sale, paid or still pending", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellSale"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/sales/{uuid}/cancel": {"post": {"summary": "Cancel an unpaid card sale and its PaymentIntent (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "The sale", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellSale"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/sales/{uuid}/receipt": {"post": {"summary": "Email a sale's receipt (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["email"], "properties": {"email": {"type": "string", "format": "email"}}}}}}, "responses": {"200": {"description": "The sale", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/MobileSellSale"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/locations/{uuid}/terminal": {"post": {"summary": "Give a location the address Stripe Terminal needs for card payments (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["line1", "city", "postal_code"], "properties": {"line1": {"type": "string"}, "line2": {"type": "string"}, "city": {"type": "string"}, "state": {"type": "string"}, "postal_code": {"type": "string"}, "country": {"type": "string", "minLength": 2, "maxLength": 2}}}}}}, "responses": {"200": {"description": "The location", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object"}}}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/store/sell/connection-token": {"post": {"summary": "A Stripe Terminal connection token for the app's card reader (needs Sell in person)", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["location_uuid"], "properties": {"location_uuid": {"type": "string", "format": "uuid"}}}}}}, "responses": {"200": {"description": "The token secret and the Terminal Location", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object", "properties": {"secret": {"type": "string"}, "terminal_location_id": {"type": "string"}}}}}}}}, "409": {"description": "The location needs its address first (terminal_address_needed)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "default": {"description": "Safe JSON error envelope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/contacts": { "get": { "summary": "Search and page selected-team contacts", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileContact" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Create contacts", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileContact" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "companyName": { "type": "string" }, "avatar_image_uuid": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "displayName" ] } } } } } }, "/contacts/import": { "post": { "summary": "Import up to 200 contacts from a JSON document", "description": "Uses the website importer. An invalid document imports nothing. Requires edit access to the selected team.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "json" ], "additionalProperties": false, "properties": { "json": { "type": "string", "minLength": 1, "maxLength": 500000 } } } } } }, "responses": { "201": { "description": "Contacts imported", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "imported": { "type": "integer" } }, "required": [ "imported" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/match-count": { "get": { "summary": "Count the contacts the native list search matches, up to 1,000", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "schema": { "type": "string", "maxLength": 150 } } ], "responses": { "200": { "description": "Match count", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "too_many": { "type": "boolean" } }, "required": [ "count", "limit", "too_many" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/bulk-delete": { "post": { "summary": "Delete up to 100 selected contacts; contacts with invoices are kept", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "uuids" ], "additionalProperties": false, "properties": { "uuids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } } }, { "type": "object", "required": [ "match", "expected_count" ], "additionalProperties": false, "properties": { "match": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "maxLength": 150 } } }, "expected_count": { "type": "integer", "minimum": 1, "maximum": 1000 } } } ] } } } }, "responses": { "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "integer" }, "skipped_with_invoices": { "type": "integer" }, "not_found": { "type": "integer" } }, "required": [ "deleted", "skipped_with_invoices", "not_found" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/{uuid}": { "get": { "summary": "Read selected-team item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileContact" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "patch": { "summary": "Update supported fields; preserve other details", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileContact" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "companyName": { "type": "string" }, "avatar_image_uuid": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string" } }, "required": [ "displayName" ] } } } } }, "delete": { "summary": "Delete selected-team item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/contacts/{uuid}/invoices": { "get": { "summary": "List invoices for a selected-team contact", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded contact invoice history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileInvoice" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/{uuid}/avatar": { "get": { "summary": "Read an attached contact photo for the selected team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "size", "required": false, "schema": { "type": "string", "enum": [ "thumb" ] } } ], "responses": { "200": { "description": "Authenticated contact photo" }, "304": { "description": "Contact photo has not changed" }, "404": { "description": "Contact or photo not found" }, "default": { "description": "Authentication, permission or server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/todos": { "get": { "summary": "Search and page selected-team todos", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "in": "query", "name": "completed", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTodo" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Create todos", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileTodo" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ] } } } } } }, "/todos/{uuid}": { "get": { "summary": "Read selected-team item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileTodo" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "patch": { "summary": "Update supported fields; preserve other details", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileTodo" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "notesMarkdown": { "type": "string", "nullable": true }, "whenDate": { "type": "string", "nullable": true }, "whenTime": { "type": "string", "nullable": true }, "deadlineDate": { "type": "string", "nullable": true }, "priority": { "type": "string", "nullable": true } } } } } } }, "delete": { "summary": "Delete selected-team item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/todos/{uuid}/complete": { "post": { "summary": "Complete To-do", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileTodo" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/todos/{uuid}/reopen": { "post": { "summary": "Reopen To-do", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileTodo" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/calendar": { "get": { "summary": "Seven-day privacy-aware agenda in account timezone", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "date", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileAgenda" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/chat/bootstrap": { "get": { "summary": "Chat bootstrap", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatBootstrap" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/chat/history": { "get": { "summary": "Chat history", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "channel_uuid", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "before_message_id", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatHistory" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/chat/poll": { "get": { "summary": "Chat poll", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "after_event_id", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatEvents" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/chat/thread": { "get": { "summary": "Chat thread", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "message_uuid", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "before_reply_id", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatThread" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/chat/presence": { "get": { "summary": "List active Chat members", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "channel_uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatPresence" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error." } } }, "post": { "summary": "Record Chat presence", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatPresence" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error." } } } }, "/chat/member-profile": { "get": { "summary": "View a Chat member profile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "user_id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatMemberProfile" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, team-membership or server error." } } } }, "/images": { "get": { "summary": "List the authenticated account image library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "all", "jpg", "png", "gif", "webp" ] } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest", "filename", "size_desc" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "maximum": 60 } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Account-owned image metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileImage" } }, "next_offset": { "type": "integer", "nullable": true }, "used_bytes": { "type": "integer" }, "quota_bytes": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset", "used_bytes", "quota_bytes" ] } } } }, "default": { "description": "Authentication, validation or server error." } } }, "post": { "summary": "Upload an image to the authenticated account library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" } }, "required": [ "image" ] } } } }, "responses": { "201": { "description": "Image metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "image": { "$ref": "#/components/schemas/MobileImage" } } } } } } } }, "default": { "description": "Authentication, validation, quota or server error." } } } }, "/images/{imageUuid}": { "get": { "summary": "View an authenticated account image", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "imageUuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "size", "required": false, "schema": { "type": "string", "enum": [ "thumb" ] } } ], "responses": { "200": { "description": "Private image bytes", "content": { "image/jpeg": {}, "image/png": {}, "image/gif": {}, "image/webp": {} } }, "304": { "description": "Cached image is current." }, "default": { "description": "Authentication, ownership or server error." } } }, "delete": { "summary": "Remove an image from the authenticated account library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "imageUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image removed." }, "default": { "description": "Authentication, ownership or server error." } } } }, "/image-converter": { "get": { "summary": "List the authenticated account's converted images", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Recent conversion results and supported settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileImageConversion" } }, "next_offset": { "type": "integer", "nullable": true }, "format_guidance": { "type": "object" }, "quality_levels": { "type": "object" }, "max_edge": { "type": "integer" }, "max_file_bytes": { "type": "integer" }, "temporary_result_ttl_hours": { "type": "integer" }, "size_presets": { "type": "array", "items": { "$ref": "#/components/schemas/MobileImageSizePreset" } }, "crop_ratios": { "type": "array", "items": { "$ref": "#/components/schemas/MobileImageCropRatio" } } }, "required": [ "data", "next_offset", "format_guidance", "quality_levels", "max_edge", "max_file_bytes", "temporary_result_ttl_hours", "size_presets", "crop_ratios" ] } } } }, "default": { "description": "Authentication, validation or server error." } } } }, "/image-converter/download": { "get": { "summary": "Download several owned conversion results as a ZIP", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "uuids", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Private ZIP download." }, "default": { "description": "Authentication, ownership, validation or download error." } } } }, "/image-converter/save": { "post": { "summary": "Save several owned conversion results to the image library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "maxItems": 12, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Save results." }, "default": { "description": "Authentication, validation or save error." } } } }, "/image-converter/batches": { "get": { "summary": "List recent image batches", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Recent batch summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileImageBatch" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Authentication or server error." } } }, "post": { "summary": "Create an image batch", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sources", "rules", "destination" ], "properties": { "sources": { "type": "array", "maxItems": 200, "items": { "type": "object" } }, "rules": { "type": "object" }, "destination": { "type": "string", "enum": [ "zip", "magpie" ] }, "name": { "type": "string", "nullable": true } } } } } }, "responses": { "201": { "description": "Created image batch.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Authentication, validation or server error." } } } }, "/image-converter/batches/preview": { "post": { "summary": "Preview the first five files in an image batch", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sources", "rules" ], "properties": { "sources": { "type": "array", "maxItems": 200, "items": { "type": "object" } }, "rules": { "type": "object" } } } } } }, "responses": { "200": { "description": "Bounded preview results.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Authentication, validation or conversion error." } } } }, "/image-converter/batches/{batchUuid}": { "get": { "summary": "Read image batch progress", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "batchUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch progress and per-file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/MobileImageBatch" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MobileImageBatchItem" } } }, "required": [ "batch", "items" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, ownership or server error." } } } }, "/image-converter/batches/{batchUuid}/download": { "get": { "summary": "Download completed image batch results as a ZIP", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "batchUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private ZIP archive.", "content": { "application/zip": {} } }, "default": { "description": "Authentication, ownership, progress or server error." } } } }, "/image-converter/batches/{batchUuid}/save": { "post": { "summary": "Save completed image batch results to the account library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "batchUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch save results.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Authentication, ownership, quota or server error." } } } }, "/image-converter/sources": { "post": { "summary": "Choose an account image as a conversion source", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_uuid" ], "properties": { "image_uuid": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Selected image source.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Authentication, ownership or validation error." } } } }, "/image-converter/sources/upload": { "post": { "summary": "Stage a device image for conversion", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Staged image source.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Authentication, validation or server error." } } } }, "/image-converter/conversions": { "post": { "summary": "Convert one image", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_key", "filename", "transform" ], "properties": { "source_key": { "type": "string" }, "filename": { "type": "string" }, "transform": { "type": "object", "additionalProperties": false } } } } } }, "responses": { "201": { "description": "Conversion result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conversion": { "$ref": "#/components/schemas/MobileImageConversion" }, "note": { "type": "string", "nullable": true } }, "required": [ "conversion", "note" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, validation or conversion error." } } } }, "/image-converter/{conversionUuid}/download": { "get": { "summary": "Download a private conversion result", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "conversionUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private converted image bytes.", "content": { "image/jpeg": {}, "image/png": {}, "image/webp": {}, "image/avif": {} } }, "default": { "description": "Authentication, ownership, expiry or server error." } } } }, "/image-converter/{conversionUuid}/save": { "post": { "summary": "Save a conversion result to the account image library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "conversionUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved conversion result and image metadata.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Authentication, ownership, quota or server error." } } } }, "/image-converter/{conversionUuid}": { "delete": { "summary": "Remove a conversion result", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "conversionUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Conversion result removed." }, "default": { "description": "Authentication, ownership or server error." } } } }, "/chat/images": { "post": { "summary": "Upload a Chat image", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" } }, "required": [ "image" ] } } } }, "responses": { "201": { "description": "The image was added to the account library for Chat.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "image": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mimetype": { "type": "string" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "displaySize": { "type": "string" } }, "required": [ "uuid", "filename", "mimetype", "width", "height", "displaySize" ] } }, "required": [ "image" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, validation, quota or server error." } } } }, "/chat/images/{imageUuid}": { "get": { "summary": "View a Chat message image", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "imageUuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "size", "required": false, "schema": { "type": "string", "enum": [ "thumb" ] } } ], "responses": { "200": { "description": "Image attached to a visible Chat message.", "content": { "image/jpeg": {}, "image/png": {}, "image/gif": {}, "image/webp": {} } }, "304": { "description": "Cached image is current." }, "default": { "description": "Authentication, conversation permission or server error." } } } }, "/chat/audio": { "post": { "summary": "Upload a Chat voice note", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "audio": { "type": "string", "format": "binary" }, "duration_ms": { "type": "integer", "maximum": 120000 } }, "required": [ "audio" ] } } } }, "responses": { "201": { "description": "The voice note was stored for a Chat message." }, "default": { "description": "Authentication, validation, quota or server error." } } } }, "/chat/files": { "post": { "summary": "Upload a bounded Chat file", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "The file was stored for a Chat message." }, "default": { "description": "Authentication, validation, quota or server error." } } } }, "/chat/files/{fileUuid}": { "get": { "summary": "Download a Chat message file", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "fileUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File attached to a visible Chat message.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Authentication, conversation permission or server error." } } } }, "/chat/audio/{audioUuid}": { "get": { "summary": "Play a Chat voice note", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "audioUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Voice note attached to a visible Chat message.", "content": { "audio/mp4": {}, "audio/3gpp": {}, "audio/mpeg": {}, "audio/ogg": {}, "audio/webm": {} } }, "default": { "description": "Authentication, conversation permission or server error." } } } }, "/chat/direct": { "post": { "summary": "Chat direct", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } }, "required": [ "user_id" ] } } } } } }, "/chat/mute-person": { "post": { "summary": "Mute or unmute one person in Chat", "description": "A muted person's messages send no push notification and play no tab sound. They still count as unread. Muting is private to the viewer.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "muted": { "type": "boolean" } }, "required": [ "muted" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "muted": { "type": "boolean" } }, "required": [ "user_id", "muted" ] } } } } } }, "/chat/create-channel": { "post": { "summary": "Chat create-channel", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string" } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } } } }, "/chat/archive-channel": { "post": { "summary": "Archive a Chat channel", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Channel archived" }, "default": { "description": "Authentication, permission, validation, rate-limit or server error." } } } }, "/chat/restore-channel": { "post": { "summary": "Restore an archived Chat channel", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Channel restored" }, "default": { "description": "Authentication, permission, validation, rate-limit or server error." } } } }, "/chat/send": { "post": { "summary": "Chat send", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/ChatMessage" }, "eventCursor": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_uuid": { "type": "string" }, "body": { "type": "string" }, "client_nonce": { "type": "string" }, "parent_message_uuid": { "type": "string" }, "image_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "audio_uuid": { "type": "string", "format": "uuid" }, "file_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "channel_uuid", "body", "client_nonce" ] } } } } } }, "/chat/read": { "post": { "summary": "Chat read", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "read": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_uuid": { "type": "string" }, "event_id": { "type": "integer" } }, "required": [ "channel_uuid", "event_id" ] } } } } } }, "/chat/delete": { "post": { "summary": "Delete a Chat message", "description": "Deletes a message when the caller has permission. Deleting a thread root also redacts its replies.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "messageUuid": { "type": "string" }, "eventCursor": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_uuid": { "type": "string" } }, "required": [ "message_uuid" ] } } } } } }, "/chat/members": { "get": { "summary": "List a channel's members", "description": "For a members-only channel, its members; managers also get pending handle invitations and live invite links. For a channel open to the team, only the team's size and whether guests are available.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "channel_uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatChannelMembers" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/invite-link": { "get": { "summary": "Read an invite link", "description": "What a channel invite link leads to, before joining. Says nothing of the channel's messages or members.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "token", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "channelUuid": { "type": "string" }, "channelName": { "type": "string" }, "teamName": { "type": "string" }, "inviterName": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "needsHandle": { "type": "boolean" }, "suggestedHandle": { "type": "string", "nullable": true } } } }, "required": [ "data" ] } } } }, "default": { "description": "Invitation unavailable, authentication or server error." } } } }, "/chat/open-to-guests": { "post": { "summary": "Make a channel members only", "description": "Admins of the channel's team, on a plan with chat guests. Everyone now in the team stays a member.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatChannelMembers" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/join": { "post": { "summary": "Join a members-only channel of the selected team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Joined", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "channelUuid": { "type": "string" } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/leave": { "post": { "summary": "Leave a members-only channel", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Left" }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/add-member": { "post": { "summary": "Add someone to a members-only channel by handle", "description": "A member of the channel's team is added at once; anyone else is sent an invitation and joins as a guest when they accept. result is added or invited.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid", "handle" ], "properties": { "channel_uuid": { "type": "string" }, "handle": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatChannelMembers" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/remove-member": { "post": { "summary": "Remove someone from a members-only channel", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid", "user_id" ], "properties": { "channel_uuid": { "type": "string" }, "user_id": { "type": "integer" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatChannelMembers" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/create-link": { "post": { "summary": "Create a channel invite link", "description": "The url carries a token that is stored only as a hash and is returned only here.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid" ], "properties": { "channel_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatChannelMembers" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/revoke-invite": { "post": { "summary": "Revoke a handle invitation or invite link", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_uuid", "invite_uuid" ], "properties": { "channel_uuid": { "type": "string" }, "invite_uuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatChannelMembers" } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/respond-invitation": { "post": { "summary": "Accept or decline a channel invitation", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invite_uuid", "response" ], "properties": { "invite_uuid": { "type": "string" }, "response": { "type": "string", "enum": [ "accept", "decline" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "channelUuid": { "type": "string", "nullable": true } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation or server error." } } } }, "/chat/join-link": { "post": { "summary": "Join a channel through an invite link", "description": "Someone without a handle passes the one they chose; it is claimed before joining.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "handle": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Joined", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "channelUuid": { "type": "string" } } } }, "required": [ "data" ] } } } }, "default": { "description": "handle_required, handle_invalid, invitation_not_found, guest_limit_reached, authentication or server error." } } } }, "/chat/support": { "post": { "summary": "Open Magpie support", "description": "The signed-in person's one support conversation with Magpie staff, created on first use. Open it like any conversation; staff messages carry author.isStaff.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conversationUuid": { "type": "string" } }, "required": [ "conversationUuid" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication or server error." } } } }, "/chat/reaction": { "post": { "summary": "Chat reaction", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "messageUuid": { "type": "string" }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string" }, "count": { "type": "integer" }, "reacted": { "type": "boolean" } } } }, "eventCursor": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "default": { "description": "Authentication, permission, validation, rate-limit or server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_uuid": { "type": "string" }, "emoji": { "type": "string" } }, "required": [ "message_uuid", "emoji" ] } } } } } }, "/notes": { "get": { "summary": "Search selected-team notes", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a note", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Note" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content_markdown": { "type": "string" } } } } } } } }, "/notes/{uuid}": { "get": { "summary": "Read a note", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Note" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit a note with resource edit access", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Note" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content_markdown", "expected_updated_at", "expected_content_markdown" ], "properties": { "content_markdown": { "type": "string" }, "expected_updated_at": { "type": "string", "format": "date-time" }, "expected_content_markdown": { "type": "string" } } } } } } }, "delete": { "summary": "Move a note to Trash as admin or creator with edit access", "description": "Moves it to Trash, where it can be restored for 30 days (GET /trash). restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notes/{uuid}/draft": { "get": { "summary": "Read the authenticated user's Note recovery draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/NoteDraft" } ], "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Save a Note recovery draft without changing the saved Note", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content_markdown" ], "properties": { "content_markdown": { "type": "string" }, "base_updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NoteDraft" } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a Note recovery draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/login": { "post": { "summary": "Password sign-in; start session or five-minute two-factor challenge", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/MobileAuthSession" }, { "$ref": "#/components/schemas/MobileTwoFactorChallenge" } ] } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "security": [] } }, "/auth/verify-2fa": { "post": { "summary": "Redeem a two-factor challenge with authenticator or recovery code", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileAuthSession" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "two_factor_token": { "type": "string" }, "code": { "type": "string" } }, "required": [ "two_factor_token", "code" ] } } } }, "security": [] } }, "/auth/logout": { "post": { "summary": "Revoke presented mobile session", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "logged_out": { "type": "boolean" } } } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/email/start": { "post": { "summary": "Email a sign-in code for the app", "description": "Public. Emails a six-digit code to the account at the address, with no link, and returns the request the app sends back with it. The same answer for every well-formed address; an address with no account gets no email. Limited per address and per connection with /login (429 rate_limited, Retry-After). 422 invalid_request or invalid_email for an empty or malformed address, 502 send_failed, 500 email_sign_in_failed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileEmailCodeRequest" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "security": [] } }, "/auth/email/code": { "post": { "summary": "Sign in to the app with an emailed code", "description": "Public. The same result as auth/login (recorded as App and email code), or the sign-in check for an account whose address was never confirmed and has something set up on it. Refusals are the same for every address: 422 code_incomplete, code_wrong or code_used_up; 429 rate_limited with Retry-After; 503 code_not_checked; 500 sign_in_failed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/MobileAuthSession" }, { "$ref": "#/components/schemas/MobileTwoFactorChallenge" }, { "$ref": "#/components/schemas/MobileSignInCheckRequired" } ] } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sign_in_request": { "type": "string" }, "code": { "type": "string", "description": "Six digits; spaces and other non-digits are dropped." } }, "required": [ "sign_in_request", "code" ] } } } }, "security": [] } }, "/team-invitations/{token}": { "get": { "summary": "Read an invitation for the authenticated recipient", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Invitation details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileTeamInvitationDetails" } }, "required": [ "data" ] } } } }, "403": { "description": "Invitation is for another account" }, "404": { "description": "Invitation not found or expired" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Accept or decline a team invitation", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "accept", "decline" ] } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated team context", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamContext" } }, "required": [ "data" ] } } } }, "403": { "description": "Invitation is for another account" }, "404": { "description": "Invitation not found or expired" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams": { "get": { "summary": "List memberships and saved default workspace", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamContext" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a shared team", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created team context", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamContext" } }, "required": [ "data" ] } } } }, "403": { "description": "The account plan does not allow another team" }, "422": { "description": "Invalid team name" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{uuid}": { "patch": { "summary": "Update shared-team name, colour or member access", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255 }, "member_access": { "type": "string", "enum": [ "edit", "view" ] }, "color": { "type": "string", "enum": [ "blue", "teal", "purple", "orange", "green", "indigo", "gold", "pink" ] } }, "minProperties": 1, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated team context", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamContext" } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin access required" }, "404": { "description": "Team not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Archive a shared team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Team archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ] } } } }, "403": { "description": "Team admin access required" }, "404": { "description": "Team not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{uuid}/members": { "get": { "summary": "List members and roles for an authorized shared team", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded team member display metadata. Team admins can manage existing member roles and membership; invitations are listed separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTeamMember" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "404": { "description": "Team not found or not authorized for the authenticated member" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{uuid}/members/{userId}": { "patch": { "summary": "Change a shared-team member role", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Member role updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "boolean", "const": true } }, "required": [ "updated" ] } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin access required" }, "404": { "description": "Team member not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a member from a shared team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Member removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ] } } } }, "403": { "description": "Team admin access required" }, "404": { "description": "Team member not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{uuid}/invitations": { "get": { "summary": "List pending invitations for a shared team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileTeamInvitation" } } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin access required" }, "404": { "description": "Team not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Send a shared-team invitation", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member" ], "default": "member" } }, "required": [ "email", "role" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Invitation sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "boolean", "const": true } }, "required": [ "sent" ] } }, "required": [ "data" ] } } } }, "403": { "description": "Team admin access required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{uuid}/invitations/{invitationUuid}": { "delete": { "summary": "Revoke a pending shared-team invitation", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitationUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invitation revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ] } } } }, "403": { "description": "Team admin access required" }, "404": { "description": "Invitation not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{uuid}/transfer-ownership": { "post": { "summary": "Transfer shared-team ownership to an administrator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "minimum": 1 } }, "required": [ "user_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Ownership transferred", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamContext" } }, "required": [ "data" ] } } } }, "403": { "description": "Current owner access required" }, "404": { "description": "Team or target administrator not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/current": { "post": { "summary": "Change the selected Personal-or-team context", "description": "A native app session changes only the app's own selection; the website keeps its own. An API key changes the account's website selection.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TeamContext" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer" } }, "required": [ "team_id" ] } } } } } }, "/search": { "get": { "summary": "Search across Personal and every team", "description": "Unlike other list endpoints this ignores the selected team: it searches every team the signed-in person is in, through each feature's own access rules, and names each result's team.", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "type": "string", "maxLength": 150 } }, { "in": "query", "name": "type", "required": false, "description": "One key from types, or omit to search everything.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SearchResults" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dashboard": { "get": { "summary": "Workspace pins and recent work", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dashboard/tools/{key}/pin": { "post": { "summary": "Pin canonical tool", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "key", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dashboard/tools/{key}/unpin": { "post": { "summary": "Unpin canonical tool", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "key", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dashboard/recent/remove": { "post": { "summary": "Remove one item from recent work (the work itself is unchanged)", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "team_id", "feature_key", "object_key" ], "properties": { "team_id": { "type": "integer" }, "feature_key": { "type": "string" }, "object_key": { "type": "string" } } } } } } } }, "/dashboard/recent/clear": { "post": { "summary": "Clear recent work in every team (the work itself is unchanged)", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dashboard/todos/{uuid}/{action}": { "post": { "summary": "Tick off or reopen a To-do shown on the app's Dashboard, in whichever team it is in", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "complete", "reopen" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string" }, "completed": { "type": "boolean" } } } } } } } }, "default": { "description": "Safe JSON error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/kanban-boards": { "get": { "summary": "Search boards in selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileKanbanBoard" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a team-only board with default columns", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileKanbanBoard" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name" ] } } } } } }, "/kanban-boards/{uuid}": { "get": { "summary": "Read board columns and bounded card lists", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileKanbanBoard" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/kanban-boards/{uuid}/cards": { "post": { "summary": "Create card in an existing board column", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KanbanCard" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "column_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "nullable": true } }, "required": [ "column_id", "title" ] } } } } } }, "/kanban-boards/{uuid}/cards/{card}": { "get": { "summary": "Read card", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KanbanCard" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit card metadata using the token captured at edit start", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KanbanCard" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "edit_token": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "nullable": true } }, "required": [ "edit_token" ] } } } } }, "delete": { "summary": "Delete card and record activity", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/kanban-boards/{uuid}/cards/{card}/move": { "post": { "summary": "Move to start or end of a column using stored ordering", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KanbanCard" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "column_id": { "type": "integer" }, "position": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "column_id", "position" ] } } } } } }, "/kanban-boards/{uuid}/cards/{card}/images": { "post": { "summary": "Attach up to ten of the actor's own library images to a card", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_uuids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } } }, "required": [ "image_uuids" ] } } } }, "responses": { "200": { "description": "The card's images after the change", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanImage" } } } } } } }, "default": { "description": "Safe JSON error; 422 for a refused image pick, 404 when the image is not on this card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/kanban-boards/{uuid}/cards/{card}/images/{image}": { "get": { "summary": "Image bytes for a card image or an image on one of its live comments", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "image", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "size", "in": "query", "schema": { "type": "string", "enum": [ "thumb" ] } } ], "responses": { "200": { "description": "Image bytes; Cache-Control: private, no-store", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Safe JSON error; 422 for a refused image pick, 404 when the image is not on this card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Take an image off a card; it stays in its owner's library", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "card", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "image", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "The card's images after the change", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanImage" } } } } } } }, "default": { "description": "Safe JSON error; 422 for a refused image pick, 404 when the image is not on this card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents": { "get": { "summary": "Search workspace documents or direct shares; list omits content", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "shared", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileDocument" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create document with canonical initial plain-text content", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDocument" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "text": { "type": "string" } }, "required": [ "title" ] } } } } } }, "/documents/import": { "post": { "summary": "Import a document from a supported file", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "format": "binary" } }, "required": [ "document" ] } } } }, "responses": { "201": { "description": "Imported document", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDocument" }, "warnings": { "type": "array", "items": { "type": "string" } } } } } } }, "default": { "description": "Authentication, permission, validation or import error." } } } }, "/documents/{uuid}/export": { "get": { "summary": "Export an authorized Document", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "pdf", "docx", "odt", "md", "html", "txt" ] } }, { "name": "review", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "review", "clean" ], "default": "review" } } ], "responses": { "200": { "description": "Private exported Document bytes", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.oasis.opendocument.text": { "schema": { "type": "string", "format": "binary" } }, "text/markdown": { "schema": { "type": "string", "format": "binary" } }, "text/html": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Authentication, permission, validation or export error." } } } }, "/documents/{uuid}/pictures/{pictureUuid}": { "get": { "summary": "Stream a picture referenced by an authorized Document", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pictureUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "thumb" ] } } ], "responses": { "200": { "description": "Private image bytes", "headers": { "Cache-Control": { "schema": { "type": "string" } } }, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Document or referenced picture not found" } } } }, "/documents/{uuid}": { "get": { "summary": "Read authorized document metadata and structured content", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDocument" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename at expected revision without rewriting content", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDocument" } } } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "title", "revision" ], "additionalProperties": false } } } } }, "delete": { "summary": "Move a document to Trash with edit access", "description": "Moves it to Trash, where it can be restored for 30 days (GET /trash). restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "default": { "description": "Safe JSON error; 409 edit_conflict for stale title/card edits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/move": { "post": { "summary": "Move a Document to another Personal or team context", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer" }, "teamId": { "type": "integer" } }, "required": [ "revision", "teamId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Document moved to the destination team" } } } }, "/documents/{uuid}/content": { "patch": { "summary": "Save structured document content at an expected revision", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "content": { "type": "object", "additionalProperties": true } }, "required": [ "revision", "title", "content" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Saved document with the new revision", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDocument" } }, "required": [ "data" ] } } } }, "409": { "description": "The submitted revision conflicts with another saved change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/accessibility": { "get": { "summary": "Run the authorized Document accessibility check", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deterministic accessibility report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentAccessibilityReport" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/collaborators": { "get": { "summary": "List direct Document collaborators", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentCollaborator" } } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add or update a direct Document collaborator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "access" ], "properties": { "username": { "type": "string" }, "access": { "type": "string", "enum": [ "viewer", "reviewer", "editor" ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/collaborators/{userId}": { "delete": { "summary": "Remove a direct Document collaborator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/comments": { "get": { "summary": "List Document comments", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentComment" } } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add an unanchored Document comment", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" }, "parentUuid": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentComment" } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/comments/{commentUuid}": { "patch": { "summary": "Resolve or reopen a Document comment", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commentUuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resolved" ], "properties": { "resolved": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentComment" } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/documents/{uuid}/history": { "get": { "summary": "List recent Document operations", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentOperation" } } } } } } }, "default": { "description": "Safe JSON error" } } } }, "/documents/{uuid}/versions": { "get": { "summary": "List named Document versions", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "default": { "description": "Safe JSON error" } } }, "post": { "summary": "Save the current Document as a named version", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 150 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "default": { "description": "Safe JSON error" } } } }, "/documents/{uuid}/versions/{versionUuid}/restore": { "post": { "summary": "Restore a named Document version as a new revision", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "versionUuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Restored as a new revision" }, "409": { "description": "Document revision changed" }, "default": { "description": "Safe JSON error" } } } }, "/documents/{uuid}/suggestions": { "get": { "summary": "List Document suggestions", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSuggestion" } } } } } } }, "default": { "description": "Safe JSON error" } } } }, "/documents/{uuid}/suggestions/{suggestionUuid}/decision": { "post": { "summary": "Accept or reject a Document suggestion", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "suggestionUuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accept" ], "properties": { "accept": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "default": { "description": "Safe JSON error" } } } }, "/repositories": { "post": { "summary": "Create a repository in the selected team", "description": "Uses the same rules and optional starter files as the website. Requires edit access to the team.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$" }, "description": { "type": "string", "maxLength": 1000 }, "public": { "type": "boolean" }, "readme": { "type": "boolean" }, "gitignore": { "type": "string", "description": "A value from starter-options, or empty" }, "license": { "type": "string", "description": "A value from starter-options, or empty" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created repository", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileRepository" } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid or duplicate name, no edit access, or unknown template" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List the selected team's repositories, or with scope=all every repository the account can reach", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "scope", "in": "query", "description": "all is for Search: every team the account can reach, each row naming its team", "schema": { "type": "string", "enum": [ "all" ] } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "visibility", "in": "query", "schema": { "type": "string", "enum": [ "private", "public" ] } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded repository metadata without Git contents or credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileRepository" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/shared": { "get": { "summary": "Repositories shared with the account from teams it is not in", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Directly shared repositories", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileRepository" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/starter-options": { "get": { "summary": "Starter .gitignore and license choices for a new repository", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Starter choices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "gitignore": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "license": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "gitignore", "license" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/tokens": { "get": { "summary": "The account's active HTTPS tokens for Git", "description": "Only the first characters of each token are returned.", "responses": { "200": { "description": "Active tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "can_read": { "type": "boolean" }, "can_write": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prefix", "can_read", "can_write", "created_at" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an HTTPS token for Git", "description": "App sessions only; an API key receives 403. The full token is in this response once and cannot be read again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "read": { "type": "boolean" }, "write": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created token", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "item": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "can_read": { "type": "boolean" }, "can_write": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prefix", "can_read", "can_write", "created_at" ] } }, "required": [ "token", "item" ] } }, "required": [ "data" ] } } } }, "403": { "description": "Requested with an API key" }, "422": { "description": "No access chosen, or name too long" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/tokens/{id}": { "delete": { "summary": "Revoke an HTTPS token", "description": "App sessions only; an API key receives 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Revoked" }, "403": { "description": "Requested with an API key" }, "404": { "description": "Token not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{uuid}": { "get": { "summary": "Read one authorized repository's safe metadata", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Repository metadata without Git contents, storage paths or credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileRepository" } }, "required": [ "data" ] } } } }, "404": { "description": "Repository not found or not authorized for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes": { "get": { "summary": "List saved QR Codes in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "static", "dynamic" ] } }, { "name": "enabled", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded QR Code metadata without payload or design data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileQrCode" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a static QR Code or a dynamic website redirect", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "auto", "url", "text", "wifi", "contact", "email", "phone", "sms", "calendar" ], "default": "auto" }, "mode": { "type": "string", "enum": [ "static", "dynamic" ], "default": "static" }, "content": { "type": "string", "maxLength": 2500 }, "ssid": { "type": "string" }, "security": { "type": "string", "enum": [ "WPA", "WEP", "NOPASS" ] }, "password": { "type": "string" }, "hidden": { "type": "boolean" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "organization": { "type": "string" }, "job_title": { "type": "string" }, "contact_phone": { "type": "string" }, "mobile": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "contact_website": { "type": "string" }, "address": { "type": "string" }, "notes": { "type": "string" }, "email_to": { "type": "string", "format": "email" }, "email_subject": { "type": "string" }, "email_body": { "type": "string" }, "phone": { "type": "string" }, "sms_phone": { "type": "string" }, "sms_message": { "type": "string" }, "event_title": { "type": "string" }, "event_start": { "type": "string" }, "event_end": { "type": "string" }, "all_day": { "type": "boolean" }, "event_location": { "type": "string" }, "event_description": { "type": "string" } }, "description": "For auto, url and text types, provide content. Structured types use their matching fields." } } } }, "responses": { "201": { "description": "Created QR Code", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileQrCodeDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Permission, validation or creation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{uuid}": { "get": { "summary": "Read one saved QR Code in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "QR Code metadata and safe destination inspection", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileQrCodeDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "QR Code not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Change a QR name, dynamic destination, enabled state or bounded design", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 } } }, { "type": "object", "additionalProperties": false, "required": [ "destination" ], "properties": { "destination": { "type": "string", "format": "uri" } } }, { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "design" ], "properties": { "design": { "$ref": "#/components/schemas/MobileQrDesignUpdate" } } } ] } } } }, "responses": { "200": { "description": "Updated QR Code", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileQrCodeDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Permission, validation or update error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a QR Code", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted QR Code", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ] } } } }, "default": { "description": "Permission or deletion error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{uuid}/pdf": { "get": { "summary": "Download a private QR Code PDF", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private QR Code PDF rendered from the saved design", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "QR Code not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{uuid}/svg": { "get": { "summary": "Download a private QR Code SVG image", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private QR Code SVG rendered from the saved design", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "description": "QR Code not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{uuid}/png": { "get": { "summary": "Download a private QR Code PNG image", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private QR Code PNG rendered from the saved design", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "QR Code not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets": { "get": { "summary": "List spreadsheets in the selected workspace or direct shares", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "shared", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded metadata list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheet" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/import": { "post": { "summary": "Import a bounded CSV or TSV Spreadsheet", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "spreadsheet": { "type": "string", "format": "binary" } }, "required": [ "spreadsheet" ] } } } }, "responses": { "201": { "description": "Imported Spreadsheet metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSpreadsheetDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}": { "get": { "summary": "Read authorized spreadsheet metadata and sheet list", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spreadsheet metadata without cell contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSpreadsheetDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/preview": { "get": { "summary": "Read a bounded first-sheet cell preview without evaluating formulas", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sheet", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "row_start", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 99980, "default": 0 } }, { "name": "column_start", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 990, "default": 0 } } ], "responses": { "200": { "description": "At most 20 rows by 10 columns and 200 cells", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSpreadsheetPreview" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/cells": { "patch": { "summary": "Edit one entered spreadsheet cell through the revisioned operation boundary", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileSpreadsheetCellUpdate" } } } }, "responses": { "200": { "description": "Saved cell and refreshed spreadsheet metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSpreadsheetDetail" }, "revision": { "type": "integer" }, "duplicate": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } }, "required": [ "data", "revision", "duplicate", "result" ] } } } }, "409": { "description": "Spreadsheet changed elsewhere" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/sheets": { "patch": { "summary": "Manage spreadsheet sheets through the revisioned operation boundary", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileSpreadsheetSheetUpdate" } } } }, "responses": { "200": { "description": "Saved sheet operation and refreshed spreadsheet metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSpreadsheetDetail" }, "revision": { "type": "integer" }, "duplicate": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } }, "required": [ "data", "revision", "duplicate", "result" ] } } } }, "409": { "description": "Spreadsheet changed elsewhere" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/collaborators": { "get": { "summary": "List direct spreadsheet collaborators", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Direct collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add or update a direct spreadsheet collaborator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "access": { "type": "string", "enum": [ "viewer", "commenter", "editor" ] } }, "required": [ "username", "access" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Updated direct collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/filter-views": { "get": { "summary": "List personal Spreadsheet Filter Views", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Personal Filter Views without cell contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetFilterView" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a personal Spreadsheet Filter View", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileSpreadsheetFilterViewInput" } } } }, "responses": { "201": { "description": "Created Filter View list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetFilterView" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/filter-views/{filterViewUuid}": { "patch": { "summary": "Update a personal Spreadsheet Filter View", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filterViewUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileSpreadsheetFilterViewInput" } } } }, "responses": { "200": { "description": "Updated Filter View list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetFilterView" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a personal Spreadsheet Filter View", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filterViewUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Remaining Filter Views", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetFilterView" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/find": { "get": { "summary": "Find entered values in an authorized Spreadsheet", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "sheet", "workbook" ], "default": "sheet" } }, { "name": "sheet", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "matchCase", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } }, { "name": "entireCell", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } } ], "responses": { "200": { "description": "Bounded Spreadsheet matches without exposing unrelated cells", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/MobileSpreadsheetFindMatch" } }, "truncated": { "type": "boolean" } }, "required": [ "matches", "truncated" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/export": { "get": { "summary": "Download a private Spreadsheet CSV export", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sheet", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private CSV export of the selected sheet", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Spreadsheet or sheet not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spreadsheets/{uuid}/collaborators/{userId}": { "delete": { "summary": "Remove a direct spreadsheet collaborator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Collaborator removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/books": { "post": { "summary": "Create a private draft book", "description": "Books belong to the account, whatever team is selected. The account's plan limits the number of books.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Created book", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookDetail" } }, "required": [ "data" ] } } } }, "403": { "description": "plan_required: the plan's book limit is reached" }, "422": { "description": "Missing or too long title" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List the authenticated user's books", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "visibility", "in": "query", "schema": { "type": "string", "enum": [ "private", "public" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded account-owned book metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBook" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/books/{id}": { "patch": { "summary": "Publish or unpublish a book", "description": "Publishing makes the book public and needs at least one section. Returning it to draft makes it private.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "published" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated book", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "Book not found for this account" }, "422": { "description": "Invalid status, or a book with no sections" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Read one book owned by the authenticated account", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Book metadata without editor content", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "Book not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/books/{id}/sections": { "post": { "summary": "Add a section at the end of the chapters", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Created section", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookSectionDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "Book not found for this account" }, "422": { "description": "Missing title or the book is full" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/books/{id}/sections/{sectionId}": { "get": { "summary": "Read one section with its Markdown text", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "sectionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Section; markdown is null when the section has formatting the app cannot edit", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookSectionDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "Section not found in this book" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Save a section's title and/or Markdown text", "description": "base_revision must be the revision the edit started from. Lines [[Picture N]] and [[Page break]] keep the section's existing pictures and page breaks.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "sectionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "markdown": { "type": "string", "maxLength": 500000 }, "base_revision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "edit_token": { "type": "string", "description": "32 hex characters, one per editing session; the first text change of a session keeps a version of the previous text" } }, "required": [ "base_revision" ] } } } }, "responses": { "200": { "description": "Saved section", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookSectionDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "Section not found in this book" }, "409": { "description": "stale_book_section: the section changed after the edit started" }, "422": { "description": "Invalid fields, or formatting the app cannot edit" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a section", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "sectionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Section not found in this book" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/books/{id}/sections/{sectionId}/move": { "post": { "summary": "Move a section", "description": "up and down swap the section with its neighbour in the same list; front, body, back and set_aside move it to the end of that list. Part dividers stay among the chapters or set aside.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "sectionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "move": { "type": "string", "enum": [ "up", "down", "front", "body", "back", "set_aside" ] }, "base_arrangement": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "move", "base_arrangement" ] } } } }, "responses": { "200": { "description": "Contents after the move", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookContents" } }, "required": [ "data" ] } } } }, "404": { "description": "Section not found in this book" }, "409": { "description": "stale_book_section: the contents changed after they were loaded" }, "422": { "description": "A move that is not possible from here" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/books/{id}/contents": { "get": { "summary": "Read a bounded book contents projection", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Book sections grouped by manuscript matter; excerpts only", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBookContents" } }, "required": [ "data" ] } } } }, "404": { "description": "Book not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links": { "get": { "summary": "Read the Links list in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Links list or null when none exists; editors receive aggregate page-view, click-through-rate, and per-link click counts" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create the Links list in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Created Links list" }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a native Links profile field", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "enum": [ "displayName", "bio" ] }, "value": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/publish": { "post": { "summary": "Publish or unpublish the Links list", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "published" ], "properties": { "published": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated publication state" }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/import": { "post": { "summary": "Create or replace named Links content from JSON", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "json" ], "properties": { "json": { "type": "string", "maxLength": 200000, "description": "A Links JSON document. Named blocks and social profiles replace the current sets; publication is unchanged." } } } } } }, "responses": { "201": { "description": "Imported Links list" }, "403": { "description": "Team edit access required" }, "422": { "description": "Invalid or oversized Links JSON" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/{uuid}": { "get": { "summary": "Read one enabled Links block in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Links block detail" }, "404": { "description": "Link not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/blocks": { "post": { "summary": "Add a Links block", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "link", "heading", "text", "divider", "magpie" ] }, "label": { "type": "string", "maxLength": 150, "description": "Required for link and text blocks; optional for heading and Magpie page blocks." }, "url": { "type": "string", "maxLength": 2000, "description": "Required for link blocks." }, "subtitle": { "type": "string", "maxLength": 300 }, "magpieTarget": { "type": "string", "enum": [ "store", "supporters", "website" ], "description": "Required for Magpie page blocks." } } } } } }, "responses": { "201": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/blocks/{uuid}": { "patch": { "summary": "Update a Links block", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 150 }, "url": { "type": "string", "maxLength": 2000 }, "subtitle": { "type": "string", "maxLength": 300 }, "magpieTarget": { "type": "string", "enum": [ "store", "supporters", "website" ] } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "404": { "description": "Link block not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a Links block", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Link block deleted" }, "403": { "description": "Team edit access required" }, "404": { "description": "Link block not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/blocks/{uuid}/move": { "post": { "summary": "Move a Links block up or down", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "direction" ], "properties": { "direction": { "type": "string", "enum": [ "up", "down" ] } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "404": { "description": "Link block not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/blocks/{uuid}/color": { "post": { "summary": "Set a link's own background colour, or return it to the page theme", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 20, "description": "#RRGGBB, or an empty string for the page theme" } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "404": { "description": "Link block not found" }, "default": { "description": "Safe JSON error; 422 when the block is not a link or the colour is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/avatar": { "post": { "summary": "Set or remove the Links header picture", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_uuid" ], "additionalProperties": false, "properties": { "image_uuid": { "type": "string", "description": "An image in the signed-in account's library, or an empty string to remove the picture" } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error; 422 when the image is not in the account's library", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/blocks/{uuid}/visibility": { "post": { "summary": "Show or hide a Links block", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "404": { "description": "Link block not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/social-links": { "get": { "summary": "List server-authorized social profile choices", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Social profile choices" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a social profile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "url" ], "properties": { "platform": { "type": "string" }, "url": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/social-links/{uuid}": { "patch": { "summary": "Update a social profile address", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Updated Links list" }, "403": { "description": "Team edit access required" }, "404": { "description": "Social profile not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a social profile", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Social profile removed" }, "403": { "description": "Team edit access required" }, "404": { "description": "Social profile not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/appearance": { "get": { "summary": "List server-authorized Links appearance choices", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Appearance choice lists" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms": { "get": { "summary": "List Forms in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Forms and pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileForm" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}": { "get": { "summary": "Read a Form in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileForm" } } } } } }, "404": { "description": "Form not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Publish or close a Form", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "published", "closed" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated Form", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileForm" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move a Form to Trash", "description": "Moves it to Trash with its responses, where it can be restored for 30 days (GET /trash). Its link and payment return pages answer not found meanwhile. restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/builder": { "get": { "summary": "Read the editable Form draft for a Form editor", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Editable Form draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormBuilder" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Save the revision-checked Form draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draft_version": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "maxLength": 150 }, "schema": { "type": "object", "additionalProperties": true } }, "required": [ "draft_version", "title", "schema" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Saved Form draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormBuilder" } }, "required": [ "data" ] } } } }, "409": { "description": "Stale Form draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/payment": { "get": { "summary": "Read native Form payment settings", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form payment settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormPayment" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Save revision-checked Form payment settings", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draft_version": { "type": "integer", "minimum": 1 }, "enabled": { "type": "boolean" }, "amount": { "type": "string", "maxLength": 20 }, "currency": { "type": "string" } }, "required": [ "draft_version", "enabled", "amount", "currency" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Saved Form payment settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormPayment" } }, "required": [ "data" ] } } } }, "409": { "description": "Stale Form draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/settings": { "get": { "summary": "Read native Form response settings", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormSettings" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update one native Form response setting", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "authenticated_only", "one_response_per_user", "notify_on_submission" ] }, "value": { "type": "boolean" } }, "required": [ "field", "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated Form settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormSettings" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/appearance": { "get": { "summary": "Read native Form appearance choices", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form appearance choices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormAppearance" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update native Form appearance", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string" } }, "required": [ "theme" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated Form appearance", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormAppearance" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/collaborators": { "get": { "summary": "List direct Form collaborators", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileFormCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add or update a direct Form collaborator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "access": { "type": "string", "enum": [ "view", "edit" ] } }, "required": [ "username", "access" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Updated Form collaborators" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/collaborators/{userId}": { "delete": { "summary": "Remove a direct Form collaborator", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Collaborator removed" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/summary": { "get": { "summary": "Read the response summary for a Form", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Question-by-question response summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormSummary" } } } } } }, "404": { "description": "Form not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/responses": { "get": { "summary": "List Form responses for review", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Match a response UUID." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "new", "reviewed", "archived" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded response review rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileFormResponse" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "404": { "description": "Form not found in this workspace" }, "422": { "description": "Invalid response status" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/responses/{responseUuid}/files/{fileUuid}": { "get": { "summary": "Download an uploaded Form response file", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "responseUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fileUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private uploaded file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Form, response, or file not found in this workspace" } } } }, "/forms/{uuid}/responses/{responseUuid}": { "get": { "summary": "Read one Form response for review", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "responseUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form response detail without stored schema or upload path", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormResponseDetail" } } } } } }, "404": { "description": "Form or response not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Change a Form response triage status", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "responseUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "new", "reviewed", "archived" ] } } } } } }, "responses": { "200": { "description": "Updated response detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFormResponseDetail" } } } } } }, "403": { "description": "Form edit access required" }, "404": { "description": "Form or response not found in this workspace" }, "422": { "description": "Invalid response status" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/{uuid}/responses/export": { "get": { "summary": "Export Form responses as CSV", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private Form response CSV export", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Form not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/idea-workspaces": { "get": { "summary": "List authorized Idea Boards in Personal or the selected team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded Idea Board metadata and pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileIdeaWorkspace" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an Idea Board in Personal or the selected team", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "201": { "description": "Created Idea Board", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileIdeaWorkspace" } } } } } }, "403": { "description": "Team edit access required or plan limit reached" }, "422": { "description": "Title required" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/idea-workspaces/{uuid}": { "get": { "summary": "Read an authorized Idea Board metadata projection", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Board metadata and at most 200 bounded item projections", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileIdeaWorkspace" } } } } } }, "404": { "description": "Idea Board not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename an Idea Board", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Renamed Idea Board" }, "403": { "description": "Team edit access required" }, "404": { "description": "Idea Board not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move an Idea Board to Trash with its canvas items", "description": "Moves it to Trash, where it can be restored for 30 days (GET /trash). restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "403": { "description": "Team edit access required" }, "404": { "description": "Idea Board not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/idea-workspaces/{uuid}/items/{itemUuid}": { "get": { "summary": "Read editable content for a supported Idea Board item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Editable native item content and position", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "uuid", "type", "x", "y", "width", "content" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "note", "todo", "link", "column" ] }, "x": { "type": "integer" }, "y": { "type": "integer" }, "width": { "type": "integer", "minimum": 120 }, "content": { "type": "object" } } } } } } } }, "403": { "description": "Team edit access required" }, "404": { "description": "Supported Idea Board item not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update supported Idea Board item content", "description": "Send { content, x, y, width } to edit an item, or only { parent_uuid } (a column UUID on the same board, or null) to move a note, to-do or link. Columns cannot be nested.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "content", "x", "y", "width" ], "additionalProperties": false, "properties": { "content": { "type": "object" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "width": { "type": "integer", "minimum": 120 } } }, { "type": "object", "required": [ "parent_uuid" ], "additionalProperties": false, "properties": { "parent_uuid": { "type": [ "string", "null" ], "format": "uuid" } } } ] } } } }, "responses": { "200": { "description": "Updated item and refreshed bounded board detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileIdeaWorkspace" } } } } } }, "403": { "description": "Team edit access required" }, "404": { "description": "Supported Idea Board item not found" }, "422": { "description": "Invalid item content" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an Idea Board canvas item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemUuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Canvas item deleted" }, "403": { "description": "Team edit access required" }, "404": { "description": "Idea Board or item not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/idea-workspaces/{uuid}/items": { "post": { "summary": "Create a supported Idea Board canvas item", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "content" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "note", "todo", "link", "column" ] }, "content": { "type": "object" } } } } } }, "responses": { "201": { "description": "Created canvas item and refreshed bounded board detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileIdeaWorkspace" } } } } } }, "403": { "description": "Team edit access required or plan limit reached" }, "404": { "description": "Idea Board not found" }, "422": { "description": "Unsupported item type or invalid item content" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/supporters": { "get": { "summary": "Read the selected workspace Supporters overview", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Bounded Supporters metadata and, for team admins, subscriber summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileSupportersOverview", "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/supporters/subscriptions": { "get": { "summary": "List the authenticated user's Supporter subscriptions", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Safe Supporter subscription summaries without billing identifiers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileSupporterSubscription" } } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/websites": { "get": { "summary": "List authorized Websites for the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "enabled", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Website metadata and pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileWebsite" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/websites/{uuid}": { "get": { "summary": "Read authorized Website metadata and safe page links", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Website detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileWebsite" } } } } } }, "404": { "description": "Website not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/websites/{uuid}/status": { "get": { "summary": "Read Website publication status", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Website status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileWebsiteStatus" } } } } } }, "404": { "description": "Website not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/websites/{uuid}/links": { "get": { "summary": "Read safe links from an authorized Website's pages", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bounded links extracted from the saved page", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileWebsiteLink" } } } } } } }, "404": { "description": "Website not found in this workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts": { "get": { "summary": "List the authenticated user's Podcasts", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "enabled", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Podcast list and pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobilePodcast" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{uuid}": { "get": { "summary": "Read one of the authenticated user's Podcasts", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Podcast detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePodcast" } } } } } }, "404": { "description": "Podcast not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{uuid}/episodes": { "get": { "summary": "List published episodes for an authenticated Podcast", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Published episode metadata and pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobilePodcastEpisode" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "404": { "description": "Podcast not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-drafts": { "get": { "summary": "List a Podcast's Solo episode drafts", "parameters": [ { "name": "podcast", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Drafts with their takes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobilePodcastDraft" } } } } } } }, "404": { "description": "Podcast not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-drafts/takes": { "post": { "summary": "Save one Solo take, creating the episode draft when episode_uuid is absent", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "podcast_uuid", "duration_ms", "audio" ], "properties": { "podcast_uuid": { "type": "string", "format": "uuid" }, "episode_uuid": { "type": "string", "format": "uuid" }, "duration_ms": { "type": "integer", "minimum": 500 }, "waveform": { "type": "string", "description": "JSON array of up to 160 peaks from 0 to 100" }, "audio": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "The draft with the new take", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePodcastDraft" } } } } } }, "422": { "description": "The take was refused; the message says why" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-drafts/{uuid}": { "get": { "summary": "Read a Solo episode draft", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePodcastDraft" } } } } } }, "404": { "description": "Draft not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Save a draft's title and description", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePodcastDraft" } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Discard a draft and every take in it", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-drafts/{uuid}/publish": { "post": { "summary": "Mix the takes into the episode MP3 and publish it", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Published", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Not publishable yet; the message says why" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-drafts/{uuid}/takes/{take}": { "delete": { "summary": "Remove one take from a draft", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "take", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePodcastDraft" } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-drafts/{uuid}/takes/{take}/audio": { "get": { "summary": "Play a draft take", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "take", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private file, with byte ranges", "content": { "audio/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/webm": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested byte range" }, "404": { "description": "File not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings": { "get": { "summary": "List a Podcast's recording sessions", "parameters": [ { "name": "podcast", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recordings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a recording session for recording with other people", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "podcast_uuid" ], "properties": { "podcast_uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "episode_uuid": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "The session, its absolute invite address and first snapshot", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/invites/{step}": { "post": { "summary": "Preview an invitation, or join it under a display name", "parameters": [ { "name": "step", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "preview", "join" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invite_token" ], "properties": { "invite_token": { "type": "string" }, "display_name": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Preview, or the participant token and session to open", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "The invitation is no longer available" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}": { "get": { "summary": "Read the recording session room", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Podcast-Participant", "in": "header", "required": false, "description": "A participant token from joining an invite. Present only when the app user is a guest of someone else's session; it is never sent in the address.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Podcast and snapshot", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Session not found for this account or participant" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a recording with its takes, uploads and exports", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}/sync": { "get": { "summary": "Room events after a cursor, and the current snapshot", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Podcast-Participant", "in": "header", "required": false, "description": "A participant token from joining an invite. Present only when the app user is a guest of someone else's session; it is never sent in the address.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Events, cursor and snapshot", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}/signals": { "get": { "summary": "Live conversation signals addressed to this participant", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Podcast-Participant", "in": "header", "required": false, "description": "A participant token from joining an invite. Present only when the app user is a guest of someone else's session; it is never sent in the address.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Signals and cursor", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}/actions": { "post": { "summary": "A room action, named as the website names it", "description": "Guests may use health, set_ready, transport, transfer_host, prepare_track, complete_track, complete_segment, recover_track, call_bootstrap and call_signal. The owner may also use set_role, remove_participant, rotate_invite, finalize_take, finish_received_audio, another_take, update_sync, update_trim, update_mix, undo_review, reset_mix, request_mix, request_zip, use_as_episode, soundboard_event_update and soundboard_event_delete.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Podcast-Participant", "in": "header", "required": false, "description": "A participant token from joining an invite. Present only when the app user is a guest of someone else's session; it is never sent in the address.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "The action's result", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Not available to participants" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}/chunks": { "post": { "summary": "Upload one chunk of this participant's local track", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Podcast-Participant", "in": "header", "required": false, "description": "A participant token from joining an invite. Present only when the app user is a guest of someone else's session; it is never sent in the address.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "trackUuid", "segmentUuid", "sequence", "mimeType", "sha256", "byteLength", "chunk" ], "properties": { "trackUuid": { "type": "string", "format": "uuid" }, "segmentUuid": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer" }, "mimeType": { "type": "string" }, "sha256": { "type": "string" }, "byteLength": { "type": "integer" }, "localStartMs": { "type": "integer" }, "localEndMs": { "type": "integer" }, "authoritativeStartMs": { "type": "integer" }, "authoritativeEndMs": { "type": "integer" }, "chunk": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Acknowledgement with the accepted sequence and checksum", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}/review": { "get": { "summary": "The finished take's tracks, timing, mix settings, markers and Soundboard events", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Review", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found, or still being finalized" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcast-recordings/{uuid}/assets/{asset}": { "get": { "summary": "Play or download a prepared track, mix, ZIP or waveform", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "download", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Private file, with byte ranges", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested byte range" }, "404": { "description": "File not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/episodes/{uuid}/audio": { "get": { "summary": "Stream a published episode to an authenticated account owner", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authenticated audio stream", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "Audio has not changed" }, "404": { "description": "Episode audio not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/security/sessions": { "get": { "summary": "List active mobile sessions for the authenticated account", "description": "Bounded, read-only session metadata. Credentials, hashes, prefixes, IP addresses and device fingerprints are omitted.", "responses": { "200": { "description": "Active mobile session metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MobileSecuritySession" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/security/sessions/{uuid}": { "delete": { "summary": "Revoke another active mobile session", "description": "Revokes an account-owned active session identified by its opaque UUID. The current bearer session cannot be revoked through this operation. Confirm the action in the client before sending it.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Opaque mobile session UUID; tokens, hashes and numeric IDs are not accepted.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Mobile session revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "revoked", "uuid" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Session is not owned by the account or is no longer active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The current bearer session cannot be revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The target is not an opaque UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing": { "get": { "summary": "Read plan status and bounded usage for the selected context", "description": "Plan and quota projection with native purchase eligibility. Stripe identifiers, customer data and payment methods are omitted.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Plan status and bounded usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBillingStatus" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/iap/sync": { "post": { "summary": "Verify an App Store or Google Play Pro purchase for the signed-in person's Personal plan", "description": "Requires a mobile session. The server checks the purchase with the store and validates its account binding before updating entitlement.", "requestBody": { "required": true, "content": {"application/json": {"schema": {"type": "object", "properties": { "store": {"type": "string", "enum": ["apple", "google"]}, "purchase_key": {"type": "string", "maxLength": 1024}, "signed_transaction": {"type": "string", "description": "Apple only: the StoreKit signed transaction (JWS) from the device. Links a subscription bought outside the app, which carries no account token, to this Personal plan if no other plan has claimed it."} }, "required": ["store", "purchase_key"]}}} }, "responses": { "200": {"description": "Verified purchase and current billing projection", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MobilePurchaseSyncResponse"}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/legal/{document}": { "get": { "summary": "Read native Terms of Service or Privacy Policy content", "parameters": [{"name": "document", "in": "path", "required": true, "schema": {"type": "string", "enum": ["terms", "privacy"]}}], "responses": { "200": {"description": "Plain-text legal document and public URL", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MobileLegalDocument"}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/my-orders/{uuid}": { "get": { "summary": "Unavailable in the native app", "description": "Mobile Store buyer orders and digital downloads are disabled for all accounts. Website buyer access is unchanged.", "parameters": [{"name": "uuid", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"410": {"description": "Mobile buyer commerce is unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/integrations": { "get": { "summary": "Read safe integration connection status for the authenticated account", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Account-owned provider status without credentials or settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileIntegrationStatus" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notification-preferences": { "get": { "summary": "Read bounded Slack meeting notification settings", "responses": { "200": { "description": "Slack destinations and notification settings without credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNotificationPreferences" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Change one Slack notification setting", "description": "Changes one Slack destination or one of the five meeting notification switches. Destination IDs are checked against the currently available Slack channels or members. Native push registration is managed automatically by the mobile app.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "enum": [ "slack_channel", "slack_dm_user", "slack_notify_new_booking", "slack_notify_confirmed", "slack_notify_cancelled", "slack_notify_rescheduled", "slack_notify_zoom_added" ] }, "value": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ] } } } } } }, "responses": { "200": { "description": "Updated notification settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNotificationPreferences" } }, "required": [ "data" ] } } } }, "409": { "description": "Slack is not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid or unavailable setting or destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/push-tokens": { "get": { "summary": "Read native push registration status", "description": "Returns counts and platforms only. Raw Expo push tokens are never returned.", "responses": { "200": { "description": "Push registration status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePushTokenStatus" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register a native Expo push token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "platform" ], "properties": { "token": { "type": "string", "maxLength": 255 }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "app_version": { "type": "string", "maxLength": 64, "nullable": true } } } } } }, "responses": { "201": { "description": "Push token registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePushTokenStatus" } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid push token or platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Revoke a native Expo push token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Push token revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePushTokenStatus" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/uploads": { "post": { "summary": "Start uploading a video as a Screen recording", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "201": { "description": "Upload started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "max_seconds": { "type": "integer" }, "chunk_bytes": { "type": "integer" }, "max_bytes": { "type": "integer" } }, "required": [ "uuid", "max_seconds", "chunk_bytes", "max_bytes" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error; 403 plan_required when the weekly limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/uploads/{uuid}": { "post": { "summary": "Append the next part of the video", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "chunk", "index" ], "properties": { "chunk": { "type": "string", "format": "binary" }, "index": { "type": "integer", "minimum": 0 }, "mime_type": { "type": "string", "enum": [ "video/mp4", "video/webm" ] } } } } } }, "responses": { "200": { "description": "Part saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "next_chunk": { "type": "integer" } } } } } } } }, "default": { "description": "Safe JSON error; 403 plan_required when the weekly limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Finish the upload; the video is discarded if its length cannot be read or exceeds the plan", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "The ready recording" }, "default": { "description": "Safe JSON error; 403 plan_required when the weekly limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Discard an unfinished upload", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Discarded" }, "default": { "description": "Safe JSON error; 403 plan_required when the weekly limit is reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings": { "get": { "summary": "List ready screen recordings owned by the authenticated account", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "oldest", "title" ], "default": "newest" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Bounded recording metadata and pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileScreenRecording" } }, "next_offset": { "type": "integer", "nullable": true } } } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/{uuid}": { "get": { "summary": "Read one ready screen recording owned by the authenticated account", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recording metadata with a same-origin Web viewer path", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileScreenRecording" } } } } } }, "404": { "description": "Recording not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename an owned screen recording", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Renamed screen recording", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileScreenRecording" } } } } } }, "404": { "description": "Recording not found for this account" }, "422": { "description": "Recording title is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move an owned screen recording to Trash", "description": "Moves it to Trash, where it can be restored for 30 days (GET /trash). Its share page, video and poster answer not found meanwhile. restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "404": { "description": "Recording not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/{uuid}/analytics": { "get": { "summary": "Read aggregate analytics for an owned screen recording", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bounded aggregate analytics without visitor identity or raw events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileScreenRecordingAnalytics" } }, "required": [ "data" ] } } } }, "404": { "description": "Recording not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/{uuid}/download": { "get": { "summary": "Download an owned screen recording", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Owner-authorized final MP4 stream", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Downloads are disabled for this recording" }, "404": { "description": "Recording or prepared file not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/{uuid}/share-options": { "get": { "summary": "List owned screen recording share-page choices", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Editable transcript Documents and published Forms available to the owner", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileScreenRecordingShareOptions" } }, "required": [ "data" ] } } } }, "404": { "description": "Recording not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screen-recordings/{uuid}/share": { "get": { "summary": "Read owned screen recording share-page settings", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current bounded share-page settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileScreenRecordingShareSettings" } }, "required": [ "data" ] } } } }, "404": { "description": "Recording not found for this account" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update owned screen recording share-page settings", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "show_download_button", "share_slug", "links", "transcript_document_uuid", "form_uuid" ], "additionalProperties": false, "properties": { "show_download_button": { "type": "boolean" }, "share_slug": { "type": "string", "maxLength": 80 }, "links": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/MobileScreenRecordingShareLink" } }, "transcript_document_uuid": { "type": "string", "format": "uuid", "maxLength": 36 }, "form_uuid": { "type": "string", "format": "uuid", "maxLength": 36 } } } } } }, "responses": { "200": { "description": "Updated bounded share-page settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileScreenRecordingShareSettings" } }, "required": [ "data" ] } } } }, "404": { "description": "Recording not found for this account" }, "422": { "description": "Share-page settings are invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/templates": { "get": { "summary": "List built-in and published Design layouts", "parameters": [{"$ref": "#/components/parameters/TeamScope"}], "responses": {"200": {"description": "Layouts with category, dimensions, description and SVG preview", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"groups": {"type": "array", "items": {"type": "object", "properties": {"key": {"type": "string"}, "label": {"type": "string"}, "templates": {"type": "array", "items": {"type": "object", "properties": {"key": {"type": "string"}, "label": {"type": "string"}, "description": {"type": "string"}, "category": {"type": "string"}, "width": {"type": "integer"}, "height": {"type": "integer"}, "preview_svg": {"type": "string"}}, "required": ["key", "label", "description", "category", "width", "height", "preview_svg"]}}}, "required": ["key", "label", "templates"]}}}, "required": ["groups"]}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs": { "get": { "summary": "List Design files in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "schema": { "type": "string", "maxLength": 150 } }, { "in": "query", "name": "view", "required": false, "schema": { "type": "string", "enum": [ "active", "archived" ], "default": "active" } } ], "responses": { "200": { "description": "Bounded workspace Design metadata without snapshots", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileDesign" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a Design file in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 150 }, "template_key": { "type": "string", "description": "Optional key from GET /designs/templates" } } } } } }, "responses": { "201": { "description": "Created Design metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesign" } }, "required": [ "data" ] } } } }, "403": { "description": "The selected workspace does not allow Design creation" }, "422": { "description": "Design title is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}": { "get": { "summary": "Read Design metadata without its snapshot", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Design metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesign" } }, "required": [ "data" ] } } } }, "404": { "description": "Design is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move a Design file to Trash", "description": "Moves it to Trash, archived or not, where it can be restored for 30 days (GET /trash). Its prototype links answer not found meanwhile. restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "403": { "description": "The actor cannot move this Design to Trash" }, "409": { "description": "Its Library is enabled in another Design (error code in_use)" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/document": { "get": { "summary": "Read the saved Design document for the native editor", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Authorized Design document and editor permissions", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"document": {"type": "object"}, "revision": {"type": "integer"}, "can_edit": {"type": "boolean"}, "can_share": {"type": "boolean"}, "can_publish_library": {"type": "boolean"}}, "required": ["document", "revision", "can_edit", "can_share", "can_publish_library"]}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs/{uuid}/operations": { "post": { "summary": "Apply one validated Design operation for an editor", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["operation_id", "client_session_id", "client_sequence", "base_revision", "type", "payload"], "additionalProperties": false, "properties": {"operation_id": {"type": "string", "format": "uuid"}, "client_session_id": {"type": "string", "format": "uuid"}, "client_sequence": {"type": "integer", "minimum": 0}, "base_revision": {"type": "integer", "minimum": 0}, "type": {"type": "string", "maxLength": 80}, "payload": {"type": "object"}, "undo_group_id": {"type": "string", "format": "uuid"}}}}}}, "responses": {"200": {"description": "Saved document, revision, and rebase state", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"revision": {"type": "integer"}, "document": {"type": "object"}, "conflicts": {"type": "array", "items": {"type": "object"}}, "skipped": {"type": "boolean"}, "rebased": {"type": "boolean"}}, "required": ["revision", "document", "conflicts", "skipped", "rebased"]}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs/{uuid}/libraries": { "get": { "summary": "List shared Design Libraries available to this file", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Libraries, enabled versions and publish permission", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"libraries": {"type": "array", "items": {"type": "object"}}, "can_publish": {"type": "boolean"}}, "required": ["libraries", "can_publish"]}}, "required": ["data"]}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} }, "post": { "summary": "Publish the current Design as a team Library", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["name"], "additionalProperties": false, "properties": {"name": {"type": "string", "maxLength": 150}, "notes": {"type": "string", "maxLength": 1000}}}}}}, "responses": {"201": {"description": "Published Library version"}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs/{uuid}/libraries/{libraryUuid}": { "post": { "summary": "Enable, update or disable a shared Library for this file", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"in": "path", "name": "libraryUuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["operation"], "additionalProperties": false, "properties": {"operation": {"type": "string", "enum": ["enable", "update", "disable"]}}}}}}, "responses": {"200": {"description": "Updated Library connections"}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs/{uuid}/prototype-shares": { "post": { "summary": "Create a private-link Prototype share", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["flow_id"], "additionalProperties": false, "properties": {"flow_id": {"type": "string", "maxLength": 80}}}}}}, "responses": {"201": {"description": "Share address and source revision"}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs/{uuid}/export": { "get": { "summary": "Export a private Design preview as SVG", "parameters": [{"$ref": "#/components/parameters/TeamScope"}, {"in": "path", "name": "uuid", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Private SVG file", "content": {"image/svg+xml": {"schema": {"type": "string", "format": "binary"}}}, "headers": {"Content-Disposition": {"schema": {"type": "string"}}}}, "default": {"description": "Safe JSON error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} } }, "/designs/{uuid}/branches": { "get": { "summary": "List up to 100 Design Branches", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesignBranches" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a Branch from Main for an editor", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 } } } } } }, "responses": { "201": { "description": "Updated Branches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesignBranches" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/branches/{branchUuid}": { "post": { "summary": "Update a Branch from Main (editor) or merge it into Main (manager)", "description": "update_from_main returns conflict_count; when it is above zero the Branch is unchanged. merge is refused unless the Branch is current with Main, and saves a version of Main first.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "branchUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "additionalProperties": false, "properties": { "operation": { "type": "string", "enum": [ "update_from_main", "merge" ] } } } } } }, "responses": { "200": { "description": "For update_from_main, MobileDesignBranches plus conflict_count. For merge, the merged Design and its Branches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/versions": { "get": { "summary": "List up to 100 saved Main versions of a Design", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Version history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesignVersionHistory" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Name the current Main version for an editor", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 } } } } } }, "responses": { "201": { "description": "Updated version history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesignVersionHistory" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/restore": { "post": { "summary": "Restore a saved Main version for a Design manager", "description": "expected_revision must equal the Design's current revision, or the request is refused with 409 revision_conflict.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version_uuid", "expected_revision" ], "additionalProperties": false, "properties": { "version_uuid": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Restored Design and its history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "design": { "$ref": "#/components/schemas/MobileDesign" }, "history": { "$ref": "#/components/schemas/MobileDesignVersionHistory" } }, "required": [ "design", "history" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/collaborators": { "get": { "summary": "List direct Design collaborators for a manager", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Direct collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileDesignCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add or update direct Design access", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "access" ], "additionalProperties": false, "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 255 }, "access": { "type": "string", "enum": [ "viewer", "commenter", "editor" ] } } } } } }, "responses": { "201": { "description": "Updated direct collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileDesignCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/collaborators/{userId}": { "delete": { "summary": "Remove direct Design access", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Access removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/comments": { "get": { "summary": "Read bounded Design comments", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Design comments and comment permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesignComments" } }, "required": [ "data" ] } } } }, "404": { "description": "Design is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a Design comment or reply", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "201": { "description": "Created Design comment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesignComment" } }, "required": [ "data" ] } } } }, "403": { "description": "The actor cannot comment on this Design" }, "422": { "description": "Comment content or parent is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/comments/{commentUuid}": { "patch": { "summary": "Resolve or reopen a Design comment", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "commentUuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resolved" ], "additionalProperties": false, "properties": { "resolved": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated bounded Design comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobileDesignComment" } } }, "required": [ "data" ] } } } }, "403": { "description": "The actor cannot update comments on this Design" }, "422": { "description": "Comment resolution is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/duplicate": { "post": { "summary": "Duplicate a Design in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Duplicated Design metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesign" } }, "required": [ "data" ] } } } }, "403": { "description": "The selected workspace does not allow Design creation" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/designs/{uuid}/archive": { "post": { "summary": "Archive or restore a Design", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "archived" ], "additionalProperties": false, "properties": { "archived": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated Design metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDesign" } }, "required": [ "data" ] } } } }, "403": { "description": "The actor cannot manage this Design" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters": { "get": { "summary": "Read the selected workspace newsletter and bounded email history", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Newsletter overview; subscriber administration remains on the Web", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterOverview" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Start a newsletter in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "description" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 150 }, "description": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Created newsletter", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPublication" } }, "required": [ "data" ] } } } }, "403": { "description": "Only a workspace admin can start a newsletter" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/posts": { "post": { "summary": "Create a Markdown newsletter draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "preview_text", "content_markdown" ], "additionalProperties": false, "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "preview_text": { "type": "string", "maxLength": 255 }, "content_markdown": { "type": "string", "minLength": 1, "maxLength": 200000 } } } } } }, "responses": { "201": { "description": "Created newsletter draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "required": [ "data" ] } } } }, "422": { "description": "Draft content is invalid or too long" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/subscribers": { "get": { "summary": "List and search selected-workspace subscriber addresses for team admins", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "pending", "unsubscribed", "removed", "suppressed", "all" ] } }, { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Bounded subscriber list and status counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterSubscriberPage" } }, "required": [ "data" ] } } } }, "403": { "description": "Only team admins can see subscriber addresses" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/subscribers/export": { "get": { "summary": "Download the complete selected-workspace subscriber CSV for team admins", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Subscriber CSV with email, name, status, source and lifecycle dates", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Only team admins can export subscriber addresses" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/subscribers/import": { "post": { "summary": "Import consented subscribers into the selected workspace newsletter as a team admin", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "pasted_addresses", "source_platform", "consent_details", "certify" ], "additionalProperties": false, "properties": { "subscriber_file": { "type": "string", "format": "binary", "description": "Optional CSV, TSV or delimited text file, up to 5 MB" }, "pasted_addresses": { "type": "string", "maxLength": 5242880, "description": "Optional pasted addresses; a file or pasted addresses must contain at least one row" }, "source_platform": { "type": "string", "maxLength": 80 }, "consent_details": { "type": "string", "maxLength": 1000 }, "certify": { "type": "string", "enum": [ "1" ] } } } } } }, "responses": { "201": { "description": "Import counts, including skipped addresses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "input_total": { "type": "integer" }, "imported_total": { "type": "integer" }, "invalid_total": { "type": "integer" }, "duplicate_total": { "type": "integer" }, "existing_total": { "type": "integer" }, "suppressed_total": { "type": "integer" } }, "required": [ "input_total", "imported_total", "invalid_total", "duplicate_total", "existing_total", "suppressed_total" ] } }, "required": [ "data" ] } } } }, "403": { "description": "Only team admins can import, or the subscriber plan limit was reached" }, "422": { "description": "Missing certification, invalid input or unreadable file" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/subscribers/{uuid}": { "delete": { "summary": "Remove a subscriber from the selected workspace newsletter", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subscriber removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ] } } } }, "403": { "description": "Only team admins can remove subscribers" }, "422": { "description": "Subscriber is unavailable or cannot be removed" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/settings": { "patch": { "summary": "Update one setting on the selected-workspace newsletter as a team admin", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "field", "value" ], "additionalProperties": false, "properties": { "field": { "type": "string", "enum": [ "title", "description", "slug", "status", "signupEnabled", "archiveEnabled", "senderName", "replyToEmail", "footerText" ] }, "value": { "type": "string", "description": "The selected setting value; toggles use 0 or 1" } } } } } }, "responses": { "200": { "description": "Updated newsletter state", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPublication" } }, "required": [ "data" ] } } } }, "403": { "description": "Only a team admin can change settings" }, "422": { "description": "Setting or value is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/{uuid}": { "get": { "summary": "Read a newsletter email and bounded Markdown body", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Newsletter email", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "required": [ "data" ] } } } }, "404": { "description": "Email is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update an editable newsletter draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "preview_text", "content_markdown" ], "additionalProperties": false, "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "preview_text": { "type": "string", "maxLength": 255 }, "content_markdown": { "type": "string", "minLength": 1, "maxLength": 200000 } } } } } }, "responses": { "200": { "description": "Updated newsletter draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "required": [ "data" ] } } } }, "422": { "description": "Only drafts can be updated" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an editable newsletter draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Newsletter draft deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "422": { "description": "Only drafts can be deleted" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/{uuid}/queue": { "post": { "summary": "Send a newsletter draft now or at a UTC time", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled_for" ], "additionalProperties": false, "properties": { "scheduled_for": { "type": "string", "nullable": true, "description": "UTC YYYY-MM-DD HH:MM:SS, or null to send now" } } } } } }, "responses": { "200": { "description": "Queued newsletter email", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "required": [ "data" ] } } } }, "403": { "description": "Plan or workspace permission does not allow sending" }, "422": { "description": "Email cannot be queued" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/{uuid}/schedule": { "post": { "summary": "Schedule a newsletter draft in the signed-in user's account time zone", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled_for_local" ], "additionalProperties": false, "properties": { "scheduled_for_local": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$", "description": "Account-local YYYY-MM-DDTHH:MM, no more than one year in the future" } } } } } }, "responses": { "200": { "description": "Scheduled newsletter email", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "required": [ "data" ] } } } }, "403": { "description": "Workspace permission or plan does not allow scheduling" }, "422": { "description": "The date or time is invalid, outside the allowed window, or the email is no longer a draft" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/{uuid}/test": { "post": { "summary": "Send a saved newsletter draft as a test to the signed-in user's email address", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "recipient": { "type": "string", "format": "email" } }, "required": [ "sent", "recipient" ] } } } }, "403": { "description": "Workspace permission does not allow sending a test" }, "422": { "description": "Email is not a draft or the account email address is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/newsletters/{uuid}/cancel": { "post": { "summary": "Cancel a queued or scheduled newsletter email", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Canceled newsletter email", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileNewsletterPost" } }, "required": [ "data" ] } } } }, "422": { "description": "Email is no longer cancelable" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations": { "get": { "summary": "List presentations in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "description": "Matches presentation titles", "schema": { "type": "string", "maxLength": 150 } } ], "responses": { "200": { "description": "Workspace presentations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/MobilePresentation" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a presentation in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "template_key" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "template_key": { "type": "string", "enum": [ "blank", "project-update", "pitch" ] } } } } } }, "responses": { "201": { "description": "Created presentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentation" } }, "required": [ "data" ] } } } }, "422": { "description": "Presentation details or permissions are invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/templates": { "get": { "summary": "List available presentation templates", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "responses": { "200": { "description": "Presentation templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobilePresentationTemplate" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}": { "get": { "summary": "Read a presentation status projection", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Presentation status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentation" } }, "required": [ "data" ] } } } }, "404": { "description": "Presentation is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move an editable presentation to Trash", "description": "Moves it to Trash, where it can be restored for 30 days (GET /trash). restore_until says when it will be deleted forever.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Moved to Trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "restore_until": { "type": "string", "format": "date-time", "description": "When it stops being restorable from Trash and is deleted forever." } }, "required": [ "deleted", "restore_until" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/help": { "get": { "summary": "Help sections and article titles, for native Help", "responses": { "200": { "description": "Sections with their articles" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/help/search": { "get": { "summary": "Search Help articles (up to 30 results)", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "type": "string", "maxLength": 150 } } ], "responses": { "200": { "description": "Matching articles" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/help/{section}/{slug}": { "get": { "summary": "One Help article as Markdown; links between articles are /help/{section}/{slug} paths", "parameters": [ { "in": "path", "name": "section", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Article with body_markdown and related articles" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/pdf": { "get": { "summary": "Download the draft as a PDF, one page per visible slide", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/slides": { "get": { "summary": "Read the draft slide outline, text and speaker notes", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Draft outline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentationOutline" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error; 409 version_conflict when expected_version is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Duplicate a slide in the draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version", "duplicate_of" ], "additionalProperties": false, "properties": { "expected_version": { "type": "integer" }, "duplicate_of": { "type": "string" } } } } } }, "responses": { "201": { "description": "Updated outline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentationOutline" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error; 409 version_conflict when expected_version is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/slides/{slideId}": { "patch": { "summary": "Change a draft slide's title, notes, visibility, text or position", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "slideId", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{4,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version" ], "minProperties": 2, "additionalProperties": false, "properties": { "expected_version": { "type": "integer" }, "title": { "type": "string", "maxLength": 150 }, "notes": { "type": "string", "maxLength": 10000 }, "hidden": { "type": "boolean" }, "texts": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 10000 } }, "position": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Updated outline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentationOutline" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error; 409 version_conflict when expected_version is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a slide from the draft; the last slide cannot be deleted", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "slideId", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{4,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_version" ], "additionalProperties": false, "properties": { "expected_version": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated outline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentationOutline" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error; 409 version_conflict when expected_version is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/collaborators": { "get": { "summary": "List direct presentation collaborators for an editor", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Direct collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobilePresentationCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add or update direct presentation access", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "access" ], "additionalProperties": false, "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 255 }, "access": { "type": "string", "enum": [ "view", "edit" ] } } } } } }, "responses": { "201": { "description": "Updated direct collaborators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobilePresentationCollaborator" } } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/collaborators/{userId}": { "delete": { "summary": "Remove direct presentation access", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Access removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/duplicate": { "post": { "summary": "Duplicate a presentation in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Duplicated presentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentation" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/publish": { "post": { "summary": "Publish the current presentation draft", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "expected_version": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Published presentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentation" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/presentations/{uuid}/share": { "post": { "summary": "Set presentation link sharing", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "private", "link" ] } } } } } }, "responses": { "200": { "description": "Updated presentation sharing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobilePresentation" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards": { "get": { "summary": "List accessible Message Boards in the selected workspace", "description": "Archived boards are left out unless view is archived, which lists the archived boards of the selected team that the account is a member of, most recently archived first. An archived board can still be opened at /boards/{slug}, where its archived_at is set.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "query", "name": "q", "required": false, "description": "Matches board names", "schema": { "type": "string", "maxLength": 150 } }, { "in": "query", "name": "view", "required": false, "description": "current lists boards that are not archived; archived lists the archived ones", "schema": { "type": "string", "enum": [ "current", "archived" ], "default": "current" } } ], "responses": { "200": { "description": "Accessible boards", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileBoard" } }, "archived_count": { "type": "integer", "description": "How many archived boards the selected team has that the account can list, whichever view was asked for" } }, "required": [ "data", "archived_count" ] } } } }, "422": { "description": "view is not current or archived (invalid_view)" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a Message Board in the selected workspace", "parameters": [ { "$ref": "#/components/parameters/TeamScope" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "slug", "description", "visibility" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "slug": { "type": "string", "minLength": 3, "maxLength": 50 }, "description": { "type": "string", "maxLength": 500 }, "visibility": { "type": "string", "enum": [ "public", "private" ] } } } } } }, "responses": { "201": { "description": "Created board", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoard" } }, "required": [ "data" ] } } } }, "422": { "description": "Board details or permissions are invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}": { "get": { "summary": "Read a Message Board and its bounded post list", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string", "enum": [ "hot", "new", "top" ], "default": "hot" } } ], "responses": { "200": { "description": "Board and posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPage" } }, "required": [ "data" ] } } } }, "404": { "description": "Board is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Change one Message Board setting for its creator or a team admin", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "field", "value" ], "additionalProperties": false, "properties": { "field": { "type": "string", "enum": [ "name", "description", "visibility" ] }, "value": { "type": "string", "maxLength": 500, "description": "Name: 2 to 100 characters. Description: up to 500 characters; empty removes it. Visibility: public or private." } } } } } }, "responses": { "200": { "description": "Updated board", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoard" } }, "required": [ "data" ] } } } }, "403": { "description": "Only the board creator or a team admin can change settings" }, "404": { "description": "Board is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an archived Message Board, for its creator or a team admin", "description": "Only an archived board can be deleted; a current one is refused with 422 validation_failed. The board is hidden with its posts, comments and votes, and its address is never given to another board. Send no request body.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Board deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "403": { "description": "Only the board creator or a team admin can archive, restore or delete it" }, "404": { "description": "Board is unavailable in the selected team" }, "422": { "description": "The board is not archived (validation_failed), or a request body was sent (invalid_request)" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/archive": { "post": { "summary": "Archive a Message Board, for its creator or a team admin", "description": "An archived board stays readable at its address but takes no posts, comments or votes, and leaves GET /boards for its archived view. Archiving an archived board changes nothing. Send no request body.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The board as it is now, with archived_at set and its comment_count", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoard" } }, "required": [ "data" ] } } } }, "403": { "description": "Only the board creator or a team admin can archive, restore or delete it" }, "404": { "description": "Board is unavailable in the selected team" }, "422": { "description": "A request body was sent (invalid_request)" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/restore": { "post": { "summary": "Restore an archived Message Board, for its creator or a team admin", "description": "The board takes posts, comments and votes again and returns to GET /boards. Restoring a board that is not archived changes nothing. Send no request body.", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The board as it is now, with archived_at null", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoard" } }, "required": [ "data" ] } } } }, "403": { "description": "Only the board creator or a team admin can archive, restore or delete it" }, "404": { "description": "Board is unavailable in the selected team" }, "422": { "description": "A request body was sent (invalid_request)" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/posts": { "post": { "summary": "Create a Message Board post", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "body_markdown", "link_url" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 3, "maxLength": 300 }, "body_markdown": { "type": "string", "maxLength": 100000 }, "link_url": { "type": "string", "maxLength": 2048 } } } } } }, "responses": { "201": { "description": "Created post", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPostDetail" } }, "required": [ "data" ] } } } }, "422": { "description": "Post details or board permissions are invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/posts/{publicId}": { "get": { "summary": "Read a Message Board post and comments", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post and comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPostDetail" } }, "required": [ "data" ] } } } }, "404": { "description": "Post is unavailable in the selected workspace" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an owned or moderated Message Board post", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/posts/{publicId}/vote": { "post": { "summary": "Vote on a Message Board post", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "integer", "enum": [ -1, 1 ] } } } } } }, "responses": { "200": { "description": "Updated post", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPostDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/posts/{publicId}/comments": { "post": { "summary": "Create a Message Board comment", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body_markdown" ], "additionalProperties": false, "properties": { "body_markdown": { "type": "string", "maxLength": 20000 }, "parent_public_id": { "type": "string", "nullable": true } } } } } }, "responses": { "201": { "description": "Updated post with comment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPostDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/posts/{publicId}/comments/{commentId}": { "delete": { "summary": "Delete an owned or moderated Message Board comment", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post with deleted comment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPostDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{slug}/posts/{publicId}/comments/{commentId}/vote": { "post": { "summary": "Vote on a Message Board comment", "parameters": [ { "$ref": "#/components/parameters/TeamScope" }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "additionalProperties": false, "properties": { "value": { "type": "integer", "enum": [ -1, 1 ] } } } } } }, "responses": { "200": { "description": "Updated post", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileBoardPostDetail" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/favicons": { "get": { "summary": "List the authenticated account's favicon projects", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Account-owned favicon projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MobileFaviconProject" } }, "next_offset": { "type": "integer", "nullable": true } }, "required": [ "data", "next_offset" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a favicon project from an account image", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_uuid" ], "additionalProperties": false, "properties": { "image_uuid": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Created favicon project", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFaviconProject" } }, "required": [ "data" ] } } } }, "422": { "description": "Image is invalid or unavailable" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/favicons/{uuid}": { "get": { "summary": "Read one account-owned favicon project", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Favicon project metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileFaviconProject" } }, "required": [ "data" ] } } } }, "404": { "description": "Favicon project not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove an account-owned favicon project", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "404": { "description": "Favicon project not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/favicons/{uuid}/download": { "get": { "summary": "Generate and download one favicon ZIP", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private favicon ZIP", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Favicon project or source image not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader": { "get": { "summary": "Read the authenticated account's RSS Reader timeline", "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string", "enum": [ "all", "unread" ], "default": "all" } }, { "in": "query", "name": "feed", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } } ], "responses": { "200": { "description": "Account-owned Reader entries and subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileReaderPage" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader/subscriptions": { "post": { "summary": "Add an account-owned Reader subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "feed" ], "additionalProperties": false, "properties": { "feed": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Created Reader subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileReaderSubscription" } }, "required": [ "data" ] } } } }, "403": { "description": "The Reader subscription plan limit was reached" }, "422": { "description": "The source is not a valid or available feed" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader/subscriptions/{feedId}": { "delete": { "summary": "Remove an account-owned Reader subscription", "parameters": [ { "in": "path", "name": "feedId", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Reader subscription removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "feed_id": { "type": "integer" } }, "required": [ "deleted", "feed_id" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Reader subscription is unavailable" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader/subscriptions/{feedId}/refresh": { "post": { "summary": "Explicitly refresh an account-owned Reader subscription", "parameters": [ { "in": "path", "name": "feedId", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Refreshed Reader subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileReaderSubscription" } }, "required": [ "data" ] } } } }, "404": { "description": "Reader subscription is unavailable" }, "422": { "description": "The subscription could not be refreshed" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader/preferences": { "patch": { "summary": "Set the Reader display mode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "view_mode" ], "additionalProperties": false, "properties": { "view_mode": { "type": "string", "enum": [ "preview", "compact", "expanded" ] } } } } } }, "responses": { "200": { "description": "Updated Reader display mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "view_mode": { "type": "string", "enum": [ "preview", "compact", "expanded" ] } }, "required": [ "view_mode" ] } }, "required": [ "data" ] } } } }, "422": { "description": "The display mode is invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader/state": { "post": { "summary": "Set stored Reader entry read state", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "item_ids", "is_read" ], "additionalProperties": false, "properties": { "item_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "integer", "minimum": 1 } }, "is_read": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated read state", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "changed": { "type": "integer" }, "is_read": { "type": "boolean" } }, "required": [ "changed", "is_read" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reader/mark-all": { "post": { "summary": "Mark Reader entries read", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "feed_id": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Reader entries marked read", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "changed": { "type": "integer" } }, "required": [ "changed" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/video-chat": { "get": { "summary": "Read Video Chat call length options", "responses": { "200": { "description": "Allowed call lengths", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "durations": { "type": "array", "items": { "type": "integer" } } }, "required": [ "durations" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/video-chat/rooms": { "post": { "summary": "Create an authenticated Video Chat room", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "duration_minutes" ], "additionalProperties": false, "properties": { "duration_minutes": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "201": { "description": "Created room and participant credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileVideoChatRoom" } }, "required": [ "data" ] } } } }, "422": { "description": "The selected call length is not available" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/video-chat/rooms/join": { "post": { "summary": "Join an authenticated Video Chat room", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 4, "maxLength": 4 } } } } } }, "responses": { "200": { "description": "Joined room and participant credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileVideoChatRoom" } }, "required": [ "data" ] } } } }, "422": { "description": "The call code is invalid or unavailable" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/video-chat/rooms/{code}/signal": { "post": { "summary": "Send an authenticated WebRTC signal to a Video Chat peer", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string", "minLength": 4, "maxLength": 4 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "kind", "payload" ], "additionalProperties": false, "properties": { "token": { "type": "string" }, "kind": { "type": "string", "enum": [ "offer", "answer", "ice", "hangup" ] }, "payload": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Signal accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cursor": { "type": "integer" } }, "required": [ "cursor" ] } }, "required": [ "data" ] } } } }, "422": { "description": "The signal is invalid or the participant is not authorized" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/video-chat/rooms/{code}/poll": { "post": { "summary": "Poll authenticated WebRTC signals for a Video Chat room", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string", "minLength": 4, "maxLength": 4 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "after" ], "additionalProperties": false, "properties": { "token": { "type": "string" }, "after": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Signals and server-owned call timing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileVideoChatPoll" } }, "required": [ "data" ] } } } }, "422": { "description": "The participant is not authorized" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault": { "get": { "summary": "Read encrypted Password Vault records", "responses": { "200": { "description": "Wrapped keys and ciphertext only", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileVaultPage" } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create the authenticated user's encrypted Password Vault", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "crypto", "vault_key" ], "additionalProperties": false, "properties": { "crypto": { "type": "object" }, "vault_key": { "type": "object" } } } } } }, "responses": { "201": { "description": "Created encrypted Password Vault", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileVaultPage" } }, "required": [ "data" ] } } } }, "422": { "description": "The encrypted records are invalid" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/password": { "patch": { "summary": "Replace the encrypted Password Vault password wrapper", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "crypto" ], "additionalProperties": false, "properties": { "crypto": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated encrypted wrapper" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/recovery": { "patch": { "summary": "Replace the encrypted Password Vault recovery wrapper", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "crypto" ], "additionalProperties": false, "properties": { "crypto": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated encrypted recovery wrapper" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/items": { "post": { "summary": "Create one encrypted Password Vault item", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "item" ], "additionalProperties": false, "properties": { "item": { "type": "object" } } } } } }, "responses": { "201": { "description": "Created encrypted item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/MobileVaultItem" } }, "required": [ "item" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/items/{uuid}": { "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "summary": "Update one encrypted Password Vault item with an expected revision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_revision", "item" ], "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "item": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated encrypted item" }, "409": { "description": "The item changed elsewhere" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Move one Password Vault item to encrypted Trash", "responses": { "200": { "description": "Item moved to Trash" }, "404": { "description": "Item not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/items/{uuid}/restore": { "post": { "summary": "Restore one Password Vault item from Trash", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Restored encrypted item" }, "404": { "description": "Item not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vault/items/{uuid}/purge": { "delete": { "summary": "Permanently delete one Password Vault item", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Item permanently deleted" }, "404": { "description": "Item not found" }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data-removal": { "get": { "summary": "Read the authenticated account's Data Removal status", "description": "Personal, read-only workflow status. Identity profile fields, report contents, queue payloads and actions remain on the website.", "responses": { "200": { "description": "Bounded Data Removal status projection", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MobileDataRemovalStatus" } }, "required": [ "data" ] } } } }, "403": { "description": "A paid personal Data Removal seat is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Safe JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }