{
    "openapi": "3.1.0",
    "info": {
        "title": "Agilis Advertising REST API",
        "version": "1.0.0",
        "summary": "Create and manage offers and events for Agilis members, estimate prices and read analytics.",
        "description": "Return codes are in the JSON body (`return_code`). They are scoped to the endpoint: the same code can mean different things on different endpoints, so read each operation's `x-return-codes`.\n\nRate limit: 60 requests a minute per client IP address. Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`; over the limit the API returns 429 with `Retry-After`.\n\nHuman-readable reference: https://www.agilis.dating/api-doc · Markdown: https://www.agilis.dating/api-doc.md",
        "contact": {
            "name": "Agilis support",
            "email": "help@agilis.dating",
            "url": "https://www.agilis.dating/api-doc"
        },
        "termsOfService": "https://www.agilis.dating/terms-and-conditions"
    },
    "servers": [
        {
            "url": "https://ads.agilis.dating",
            "description": "Production. TEST or LIVE is chosen by the API key (pk_test_ / pk_live_) and the environment parameter."
        }
    ],
    "security": [
        {
            "apiKey": []
        }
    ],
    "tags": [
        {
            "name": "Offers"
        },
        {
            "name": "Events"
        }
    ],
    "paths": {
        "/categories": {
            "get": {
                "operationId": "listCategories",
                "summary": "Category List",
                "description": "Returns all active categories available to the organisation that owns the API key. It is typically called before creating an offer, because offer creation requires a valid category ID returned by this endpoint.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#categoryListSection"
                },
                "responses": {
                    "200": {
                        "description": "Categories retrieved successfully."
                    },
                    "401": {
                        "description": "Invalid API key or disabled account."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/interests": {
            "get": {
                "operationId": "listInterests",
                "summary": "Interest List",
                "description": "Returns the interests available for offer targeting. Call it before creating an offer if you intend to use the optional `interests` array, which restricts the offer to users who have selected at least one of the interests supplied.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#interestListSection"
                },
                "responses": {
                    "200": {
                        "description": "Interests retrieved successfully."
                    },
                    "401": {
                        "description": "Invalid API key or disabled account."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/offers/price-estimate": {
            "post": {
                "operationId": "estimateOfferPrice",
                "summary": "Offer Price Estimate",
                "description": "Calculates what an offer will cost before it is created: its size in Ad Units (duration in hours × the number of Agilis users it would reach) and what those units cost in money. Only active, non-banned accounts are counted. Pass the same `gender` and `interests` values you intend to create the offer with, otherwise the estimate will be higher than the amount actually charged.\n\n`price_estimate` is a number of **Ad Units**, not money. `estimated_cost` is the **money** the offer will cost, and is the figure to compare with your balance.\n\nThere is no `currency` parameter: the estimate is always in your organisation's billing currency, named in the response's `currency` field.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#priceEstimateSectionid"
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "start_datetime": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC. Now or later: a start more than 60 seconds before now (UTC) is refused with `E1`. Example: `\"2027-07-10T08:00:00Z\"`"
                                    },
                                    "end_datetime": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC. Example: `\"2027-07-12T20:30:00Z\"`"
                                    },
                                    "location": {
                                        "type": "array",
                                        "items": {
                                            "type": "number"
                                        },
                                        "maxItems": 2,
                                        "minItems": 2,
                                        "description": "Latitude and longitude. Example: `[51.5074, -0.1278]`"
                                    },
                                    "radius": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 30,
                                        "description": "Miles, minimum 5, maximum 30. Example: `10`"
                                    },
                                    "gender": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "Male",
                                                "Female",
                                                "Non-binary",
                                                "All"
                                            ]
                                        },
                                        "description": "One or more of `Male`, `Female`, `Non-binary`, `All`. Omit, or include `All`, to reach every gender. Example: `[\"Male\", \"Female\"]`"
                                    },
                                    "interests": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "description": "Interest ids from `GET /interests`. A user matches if they share any of them. Omit to apply no interest filter. Example: `[3, 7]`"
                                    },
                                    "environment": {
                                        "type": "string",
                                        "enum": [
                                            "TEST",
                                            "LIVE",
                                            "test",
                                            "live"
                                        ],
                                        "description": "`TEST` or `LIVE`. Defaults to your API key's own mode. If sent, it must be your key's mode (HTTP 403 otherwise). The Ad Unit price is the same in both."
                                    }
                                },
                                "required": [
                                    "start_datetime",
                                    "end_datetime",
                                    "location",
                                    "radius"
                                ]
                            },
                            "example": {
                                "start_datetime": "2027-07-10T08:00:00Z",
                                "end_datetime": "2027-07-12T20:30:00Z",
                                "location": [
                                    51.5074,
                                    -0.1278
                                ],
                                "radius": 10,
                                "gender": [
                                    "Male",
                                    "Female"
                                ],
                                "interests": [
                                    3,
                                    7
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "S1: Estimate calculated successfully."
                    },
                    "400": {
                        "description": "E1: One or more inputs are missing or invalid, or `start_datetime` is in the past (more than 60 seconds before now).\n\nE2: A date/time is not in valid ISO 8601 format.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication failure."
                    },
                    "403": {
                        "description": "E1: `environment` is not your API key's mode.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Estimate calculated successfully.",
                    "E1": "One or more inputs are missing or invalid, or `start_datetime` is in the past (more than 60 seconds before now). / `environment` is not your API key's mode.",
                    "E2": "A date/time is not in valid ISO 8601 format."
                }
            }
        },
        "/offers": {
            "post": {
                "operationId": "createOffer",
                "summary": "Create Offer",
                "description": "Creates a new offer for the authenticated advertiser. The request is sent as `multipart/form-data` with the offer image supplied as a binary file stream. The image is checked by automated content moderation before the offer is created: if it fails, nothing is created and nothing is charged.\n\n**Paying by Stripe link** (`payment_method=E`): the offer is created in **Awaiting Payment** and the response carries a `payment_url`. Stripe's `checkout.session.completed` webhook activates it: **Active** if its start has passed, **Scheduled** if not. An organisation registered in the UK pays VAT at 20% on top, as a separate line on the Stripe page. Stripe will not take a card payment below its minimum for the currency (for example £0.30, US$0.50 or €0.50): such an offer is refused with `E1`.\n\n**Paying from balance** (`payment_method=B`): the offer's price is deducted at once, from the balance of the offer's own mode (TEST and LIVE balances are separate). Compare your balance with `estimated_cost` from the price estimate, never `price_estimate`.\n\nThere is no `currency` parameter: every offer is priced and charged in your organisation's billing currency, named in the response.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#createOfferSectionid"
                },
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "A unique value you generate per offer (for example a UUID v4). Replaying the same key safely retries the request without creating a duplicate offer or a second Stripe payment; the original response, including any `payment_url`, is returned verbatim. Missing: HTTP 400 / `E1`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "type": "integer",
                                        "description": "A valid category ID from the Category List API. Example: `1`"
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "description": "Up to 40 characters. Example: `\"20% off summer sale\"`"
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Up to 500 characters. Example: `\"Discount valid through July\"`"
                                    },
                                    "terms_and_conditions": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Up to 500 characters. Example: `\"Valid online only.\"`"
                                    },
                                    "advertised_name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "The business name members see on the offer instead of your organisation's trading name — for example when an agency advertises for a client. Up to 100 characters; must not start with http://, https:// or www.; no HTML or line breaks. Omit or send empty to show your trading name. You must be authorised by the business you name. Invoices and analytics stay in your organisation's name. Example: `\"Brighton Bakehouse\"`"
                                    },
                                    "push_notification_title": {
                                        "type": "string",
                                        "minLength": 5,
                                        "maxLength": 50,
                                        "description": "The title of the notification sent to members who chose to get offer notifications, shown on their lock screen as you write it (it is not translated). 5 to 50 characters. Missing: `E10`; too short: `E11`; too long: `E12`; refused by content moderation: `E13`. Example: `\"20% off this summer\"`"
                                    },
                                    "push_notification_message": {
                                        "type": "string",
                                        "minLength": 5,
                                        "maxLength": 150,
                                        "description": "The notification's message, under the title. 5 to 150 characters; phones cut it at about 100, so keep it short. Same return codes as `push_notification_title`. Example: `\"Show this at the till for 20% off everything until the end of July.\"`"
                                    },
                                    "button_preset": {
                                        "type": "string",
                                        "enum": [
                                            "claim_offer",
                                            "visit_website",
                                            "install_app",
                                            "book_now",
                                            "get_directions",
                                            "custom"
                                        ],
                                        "description": "The words on the offer's button in the Agilis apps and web app: `claim_offer` (Claim Offer, the default when omitted or empty), `visit_website` (Visit our website), `install_app` (Install our app), `book_now` (Book now), `get_directions` (Get directions) or `custom` (your own words, in `button_text`). Ready-made texts are shown in each member's app language. Whatever the text, the button opens your `url`. Any other value: `E14`. Example: `\"book_now\"`"
                                    },
                                    "button_text": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 20,
                                        "description": "Your own button text: required when `button_preset` is `custom`, ignored otherwise. Plain text on one line, 1 to 20 characters after trimming, shown exactly as you write it in every language (it is not translated). Missing, empty, with a line break or with HTML: `E15`; over 20 characters: `E16`. Example: `\"Show this at the bar\"`"
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "Your offer page. Example: `\"https://advertiseroffer.com\"`"
                                    },
                                    "image": {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                        "description": "JPG, PNG or GIF, maximum 5 MB, sent as a binary file stream. Recommended size: `1080x1080px`"
                                    },
                                    "location": {
                                        "type": "array",
                                        "items": {
                                            "type": "number"
                                        },
                                        "maxItems": 2,
                                        "minItems": 2,
                                        "description": "Latitude and longitude as two values. Example: `[51.5074, -0.1278]`"
                                    },
                                    "radius": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 30,
                                        "description": "Radius in miles, minimum 5, maximum 30. Example: `10`"
                                    },
                                    "gender": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "Male",
                                                "Female",
                                                "Non-binary",
                                                "All"
                                            ]
                                        },
                                        "description": "Target specific genders. One or more of `Male`, `Female`, `Non-binary`, `All`. Omitting the field, or including `All`, reaches every gender. Narrowing this reduces the audience and therefore the price. Example: `[\"Male\", \"Female\"]`"
                                    },
                                    "interests": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "description": "Target users by interest, using ids from `GET /interests`. A user matches if they share **any** of the interests supplied. Omitting the field applies no interest filter. Narrowing this reduces the audience and therefore the price. Example: `[3, 7]`"
                                    },
                                    "start_datetime": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC. Now or later: a start more than 60 seconds before now (UTC) is refused with `E1`. Example: `\"2027-07-10T08:00:00Z\"`"
                                    },
                                    "expiry_datetime": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC; at least 60 seconds after `start_datetime`. Example: `\"2027-07-12T20:30:00Z\"`"
                                    },
                                    "payment_method": {
                                        "type": "string",
                                        "enum": [
                                            "E",
                                            "B"
                                        ],
                                        "description": "`E` = Stripe payment link by email; `B` = deduct from organisation balance (the balance of the offer's mode: TEST and LIVE balances are separate). For `E`, an organisation registered in the UK is charged VAT at 20% on top, as a separate line on the Stripe payment page. The offer's price and balance stay net of VAT."
                                    },
                                    "environment": {
                                        "type": "string",
                                        "enum": [
                                            "TEST",
                                            "LIVE"
                                        ],
                                        "description": "`TEST` or `LIVE`, in capitals. Must be your API key's own mode: a `pk_live_` key creates LIVE offers only, a `pk_test_` key TEST offers only."
                                    }
                                },
                                "required": [
                                    "category_id",
                                    "title",
                                    "description",
                                    "push_notification_title",
                                    "push_notification_message",
                                    "url",
                                    "image",
                                    "location",
                                    "radius",
                                    "start_datetime",
                                    "expiry_datetime",
                                    "payment_method",
                                    "environment"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "S1: Offer created: payment link issued (`E`), or Active/Scheduled if paid from balance (`B`).\n\nE2: The image failed automated content moderation: nothing created. Choose a different image.\n\nE3: The organisation's balance is less than the offer's cost (`payment_method=B` only): top up and retry."
                    },
                    "400": {
                        "description": "E1: One or more inputs are missing or invalid: an invalid datetime, a duration under 60 seconds, a radius outside 5 to 30 miles, an oversized image or wrong file type, an unrecognised `gender` value, an unknown `interests` id, or an `advertised_name` over 100 characters, starting with http://, https:// or www., or containing HTML or a line break.\n\nE1: `start_datetime` is more than 60 seconds before now (UTC): nothing created or charged. Message: \"start_datetime cannot be in the past. Use the current time or later.\"\n\nE1: A card payment (`payment_method=E`) below Stripe's minimum for your currency: nothing created; the message names the minimum.\n\nE1: The `Idempotency-Key` header is missing. Message: \"Idempotency-Key header is required.\"\n\nE4: Offer quota limit exceeded: the user or organisation has reached its maximum number of offers.\n\nE5: No Agilis users match the targeting supplied: nothing created. Widen the radius or broaden the `gender` or `interests` targeting.\n\nE6: Your billing currency cannot be billed right now: nothing created or charged. The message is either `Your organisation's currency (XYZ) is not one Agilis bills in. An Org Admin can choose a supported billing currency in the Ad Portal. You have not been charged.` or `Prices in XYZ are temporarily unavailable because the exchange rate is out of date. Please try again later. You have not been charged.`, with your currency code in place of XYZ.\n\nE10: `push_notification_title` or `push_notification_message` is missing or empty: nothing created or charged. The message names the field, for example \"push_notification_title is required.\"\n\nE11: `push_notification_title` or `push_notification_message` is shorter than 5 characters: nothing created or charged. The message names the field.\n\nE12: `push_notification_title` is over 50 characters, or `push_notification_message` over 150: nothing created or charged. The message names the field and its limit.\n\nE13: The notification text failed automated content moderation: nothing created or charged. The message names the field, for example \"push_notification_message can't be used in a notification. Please change it.\"\n\nE14: `button_preset` is not one of `claim_offer`, `visit_website`, `install_app`, `book_now`, `get_directions` or `custom`: nothing created or charged.\n\nE15: `button_preset` is `custom` and `button_text` is missing, empty, or contains a line break or HTML: nothing created or charged. Message: \"button_text is required when button_preset is custom, as plain text on one line.\"\n\nE16: `button_text` is over 20 characters: nothing created or charged. Message: \"button_text must be 20 characters or fewer.\"",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication failure."
                    },
                    "403": {
                        "description": "E1: `environment` is not your API key's mode: nothing created or charged. Use a key created in that mode.\n\nE9: Your organisation has not accepted the current Agilis Advertising Terms and Conditions: nothing created or charged. An Org Admin must accept them in the Ad Portal ([adportal.agilis.dating](https://adportal.agilis.dating)); then retry with the same `Idempotency-Key`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The `Idempotency-Key` was reused while the first request is still being processed: retry shortly."
                    },
                    "422": {
                        "description": "The `Idempotency-Key` was reused with a different payload."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Offer created: payment link issued (`E`), or Active/Scheduled if paid from balance (`B`).",
                    "E1": "One or more inputs are missing or invalid: an invalid datetime, a duration under 60 seconds, a radius outside 5 to 30 miles, an oversized image or wrong file type, an unrecognised `gender` value, an unknown `interests` id, or an `advertised_name` over 100 characters, starting with http://, https:// or www., or containing HTML or a line break. / `start_datetime` is more than 60 seconds before now (UTC): nothing created or charged. Message: \"start_datetime cannot be in the past. Use the current time or later.\" / A card payment (`payment_method=E`) below Stripe's minimum for your currency: nothing created; the message names the minimum. / The `Idempotency-Key` header is missing. Message: \"Idempotency-Key header is required.\" / `environment` is not your API key's mode: nothing created or charged. Use a key created in that mode.",
                    "E2": "The image failed automated content moderation: nothing created. Choose a different image.",
                    "E3": "The organisation's balance is less than the offer's cost (`payment_method=B` only): top up and retry.",
                    "E4": "Offer quota limit exceeded: the user or organisation has reached its maximum number of offers.",
                    "E5": "No Agilis users match the targeting supplied: nothing created. Widen the radius or broaden the `gender` or `interests` targeting.",
                    "E6": "Your billing currency cannot be billed right now: nothing created or charged. The message is either `Your organisation's currency (XYZ) is not one Agilis bills in. An Org Admin can choose a supported billing currency in the Ad Portal. You have not been charged.` or `Prices in XYZ are temporarily unavailable because the exchange rate is out of date. Please try again later. You have not been charged.`, with your currency code in place of XYZ.",
                    "E10": "`push_notification_title` or `push_notification_message` is missing or empty: nothing created or charged. The message names the field, for example \"push_notification_title is required.\"",
                    "E11": "`push_notification_title` or `push_notification_message` is shorter than 5 characters: nothing created or charged. The message names the field.",
                    "E12": "`push_notification_title` is over 50 characters, or `push_notification_message` over 150: nothing created or charged. The message names the field and its limit.",
                    "E13": "The notification text failed automated content moderation: nothing created or charged. The message names the field, for example \"push_notification_message can't be used in a notification. Please change it.\"",
                    "E14": "`button_preset` is not one of `claim_offer`, `visit_website`, `install_app`, `book_now`, `get_directions` or `custom`: nothing created or charged.",
                    "E15": "`button_preset` is `custom` and `button_text` is missing, empty, or contains a line break or HTML: nothing created or charged. Message: \"button_text is required when button_preset is custom, as plain text on one line.\"",
                    "E16": "`button_text` is over 20 characters: nothing created or charged. Message: \"button_text must be 20 characters or fewer.\"",
                    "E9": "Your organisation has not accepted the current Agilis Advertising Terms and Conditions: nothing created or charged. An Org Admin must accept them in the Ad Portal ([adportal.agilis.dating](https://adportal.agilis.dating)); then retry with the same `Idempotency-Key`."
                }
            },
            "get": {
                "operationId": "listOffers",
                "summary": "View Offers",
                "description": "Returns a **paginated** list of offers created by the authenticated advertiser for the requested environment, newest first. Offers whose image was rejected by content moderation are never created, so they are not returned, and deleted offers are excluded. Page through results with `limit` and `cursor`.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#viewOfferSectionid"
                },
                "parameters": [
                    {
                        "name": "environment",
                        "in": "query",
                        "required": true,
                        "description": "`test` or `live` (case-insensitive). Must be your API key's own mode. Example: `/offers?environment=test`",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "test",
                                "live",
                                "TEST",
                                "LIVE"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Page size. Default `20`, maximum `100`.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "description": "Opaque token from the previous page's `next_cursor`. Omit for the first page.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "offer_status",
                        "in": "query",
                        "required": false,
                        "description": "Lifecycle filter: `awaiting_payment`, `active`, `paused` or `ended` (case-insensitive).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "awaiting_payment",
                                "active",
                                "paused",
                                "ended"
                            ]
                        }
                    },
                    {
                        "name": "created_after",
                        "in": "query",
                        "required": false,
                        "description": "ISO 8601, UTC. Offers created at or after this time.",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "created_before",
                        "in": "query",
                        "required": false,
                        "description": "ISO 8601, UTC. Offers created at or before this time.",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Page returned (empty `data` array if none match)."
                    },
                    "400": {
                        "description": "Invalid query parameter (`limit`, `cursor`, `offer_status` or date)."
                    },
                    "401": {
                        "description": "Invalid API key or disabled account."
                    },
                    "403": {
                        "description": "`environment` is not your API key's mode."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/offers/{offer_id}/pause": {
            "post": {
                "operationId": "pauseOffer",
                "summary": "Pause Offer",
                "description": "Pauses a running offer. The offer must belong to the account that owns the API key and be in the key's mode (TEST or LIVE). Any other offer returns HTTP 401 with `E1`. Time spent paused is Unused Time: it is credited to your balance if you later delete the offer.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#pauseResumeOfferSectionid"
                },
                "parameters": [
                    {
                        "name": "offer_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `45`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "S1: Offer paused successfully.\n\nE2: Offer has already ended.\n\nE3: Offer is already paused.\n\nE5: Offer is awaiting payment."
                    },
                    "401": {
                        "description": "E1: Invalid API key, disabled account, or the offer does not belong to this account or is in the other mode.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Offer paused successfully.",
                    "E1": "Invalid API key, disabled account, or the offer does not belong to this account or is in the other mode.",
                    "E2": "Offer has already ended.",
                    "E3": "Offer is already paused.",
                    "E5": "Offer is awaiting payment."
                }
            }
        },
        "/offers/{offer_id}/resume": {
            "post": {
                "operationId": "resumeOffer",
                "summary": "Resume Offer",
                "description": "Resumes a paused offer. The offer must belong to the account that owns the API key and be in the key's mode. Any other offer returns HTTP 401 with `E1`.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#resumeOfferSectionid"
                },
                "parameters": [
                    {
                        "name": "offer_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `45`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "S2: Offer resumed successfully.\n\nE2: Offer has already ended.\n\nE4: Offer is already running.\n\nE5: Offer is awaiting payment."
                    },
                    "401": {
                        "description": "E1: Invalid API key, disabled account, or the offer does not belong to this account or is in the other mode.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S2": "Offer resumed successfully.",
                    "E1": "Invalid API key, disabled account, or the offer does not belong to this account or is in the other mode.",
                    "E2": "Offer has already ended.",
                    "E4": "Offer is already running.",
                    "E5": "Offer is awaiting payment."
                }
            }
        },
        "/offers/{offer_id}/analytics": {
            "get": {
                "operationId": "getOfferAnalytics",
                "summary": "View Offer Analytics",
                "description": "Returns view and click metrics for a specific offer over the requested time interval. The offer must belong to the account that owns the API key and be in the key's mode.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#analyticsSectionid"
                },
                "parameters": [
                    {
                        "name": "offer_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `45`",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "interval",
                        "in": "query",
                        "required": true,
                        "description": "One of `24h`, `7d`, `30d`, `60d`, `90d` or `all`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "24h",
                                "7d",
                                "30d",
                                "60d",
                                "90d",
                                "all"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Analytics returned successfully."
                    },
                    "401": {
                        "description": "Invalid API key, disabled account, or the offer does not belong to this account or is in the other mode."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/offers/{offer_id}": {
            "delete": {
                "operationId": "deleteOffer",
                "summary": "Delete Offer",
                "description": "Deletes an offer belonging to the authenticated account, in your API key's mode (an offer of the other mode is not found).\n\n**Awaiting Payment:** the offer's Stripe payment page is closed first, so it can no longer be paid. If Stripe reports that the payment has just been completed, or the page cannot be closed, nothing is deleted (`E6`, `E7` below).\n\n**Paid offers** (Active, Scheduled or Paused): the offer's Unused Time is credited to your balance in the offer's own mode. Unused Time is the part of the scheduled period in which the offer did not run: the time from the deletion to the scheduled end, plus any time it spent paused. An offer deleted before it starts is credited in full. The credit is net of VAT and goes to your balance, never back to a card.",
                "tags": [
                    "Offers"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#deleteOfferSectionid"
                },
                "parameters": [
                    {
                        "name": "offer_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `45`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "S1: Offer deleted successfully."
                    },
                    "401": {
                        "description": "E1: Invalid input, or \"Offer not found\": the offer does not belong to this account or is in the other mode.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "E6: The payment for this offer has just been completed, so it is no longer awaiting payment. Nothing has been deleted. Retrieve the offer again; if you still delete it, its Unused Time is credited to your balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "E7: The payment page could not be closed. Nothing has been deleted. Try again in a few minutes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Offer deleted successfully.",
                    "E1": "Invalid input, or \"Offer not found\": the offer does not belong to this account or is in the other mode.",
                    "E6": "The payment for this offer has just been completed, so it is no longer awaiting payment. Nothing has been deleted. Retrieve the offer again; if you still delete it, its Unused Time is credited to your balance.",
                    "E7": "The payment page could not be closed. Nothing has been deleted. Try again in a few minutes."
                }
            }
        },
        "/event-categories": {
            "get": {
                "operationId": "listEventCategories",
                "summary": "Event Categories",
                "description": "Returns the Agilis event categories, **for display**: for example to label an event in your own system with the category the API chose for it. It is not an input. The category of an event is determined from its title, description and venue name (see [Preview Event](https://www.agilis.dating/api-doc#previewEventSectionid)). Names are returned in the language of your `Accept-Language` header, falling back to English.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#eventCategoriesSectionid"
                },
                "responses": {
                    "200": {
                        "description": "Categories returned successfully."
                    },
                    "401": {
                        "description": "Missing or invalid API key, or disabled account."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/event-currencies": {
            "get": {
                "operationId": "listEventCurrencies",
                "summary": "Event Currencies",
                "description": "The currency codes a ticket price may be quoted in: every currency with an exchange rate on file, which is what lets the app sort events by price across currencies. Use one of these for `currency` on publish and edit. This is the currency members see on the price pill; it has no effect on what you are charged.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#eventCurrenciesSectionid"
                },
                "responses": {
                    "200": {
                        "description": "Currencies returned successfully."
                    },
                    "401": {
                        "description": "Missing or invalid API key, or disabled account."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/event-config": {
            "get": {
                "operationId": "getEventConfig",
                "summary": "Event Config",
                "description": "What publishing costs your organisation, your balance, whether LIVE publishing is open, the accepted currencies and the image limits. Useful before a publish, or to show the fee in your own system. `listing_fee` is £10 converted at the day's European Central Bank reference rate into your organisation's billing currency (`currency`); `exchange_rate_per_gbp` is the rate used and `exchange_rate_date` its date (`1` and `null` for GBP). All three are `null` when your billing currency cannot be billed right now (see `E6` on Publish Event). `environment` is your API key's mode (`TEST` or `LIVE`), and `balance` and `organisation_balance` are the balances for that mode: **TEST and LIVE balances are separate**, so a TEST key never shows the LIVE balance.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#eventConfigSectionid"
                },
                "responses": {
                    "200": {
                        "description": "Returned successfully."
                    },
                    "401": {
                        "description": "Missing or invalid API key, or disabled account."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/events/preview": {
            "post": {
                "operationId": "previewEvent",
                "summary": "Preview Event",
                "description": "Shows you what `POST /events` would do, **without publishing or charging**: the category your wording will get, the fee and your balance, and — if you include an image — the processed picture with its 16:9 crop applied, plus a `preview_token` that `POST /events` accepts instead of the file, so the published image is byte-for-byte the one you saw. Same fields as `POST /events`; `image` and `payment_method` are optional and no `Idempotency-Key` is needed. A rejected image returns `E2` here, before any payment. **Rate-limited** per organisation (60 previews per hour): each preview costs an image check and a classification.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#previewEventSectionid"
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "description": "The full field set of `POST /events`, validated exactly as on publish."
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "The full field set of `POST /events`, validated exactly as on publish."
                                    },
                                    "venue_name": {
                                        "type": "string",
                                        "description": "The full field set of `POST /events`, validated exactly as on publish."
                                    },
                                    "image": {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                        "description": "JPG or PNG, detected from the file's content (not its name), up to **10 MB**, at least **1280 × 720** pixels. Members see events at 16:9: the image is scaled to fill a 16:9 frame with its centre kept and the overflow trimmed (a *centred cover crop*), never stretched or letterboxed. Pass `crop[x]`, `crop[y]`, `crop[w]` to choose the area yourself. If the area would be below 1280 × 720 the image is rejected rather than enlarged. Every image is decoded and re-encoded (so only a fresh copy is stored, with EXIF data including GPS removed), content-moderated, and scanned. Use `POST /events/preview` to see the result before paying."
                                    },
                                    "crop[x": {
                                        "type": "integer",
                                        "description": "With `image`: the top-left corner and width, in pixels of the uploaded image, of the 16:9 area to use. The height is derived. Minimum width 1280. Omit for the centred cover crop."
                                    },
                                    "crop[y": {
                                        "type": "integer",
                                        "description": "With `image`: the top-left corner and width, in pixels of the uploaded image, of the 16:9 area to use. The height is derived. Minimum width 1280. Omit for the centred cover crop."
                                    },
                                    "crop[w": {
                                        "type": "integer",
                                        "description": "With `image`: the top-left corner and width, in pixels of the uploaded image, of the 16:9 area to use. The height is derived. Minimum width 1280. Omit for the centred cover crop."
                                    },
                                    "environment": {
                                        "type": "string",
                                        "enum": [
                                            "TEST",
                                            "LIVE"
                                        ],
                                        "description": "`TEST` or `LIVE`. Must be your API key's own mode (HTTP 403 otherwise). Decides whether `balance_after` subtracts the fee; `balance` is the balance for that mode."
                                    }
                                },
                                "required": [
                                    "environment"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "S1: Preview returned. `category` is what publishing this wording will get; `image.preview_token` is single-use, bound to your organisation and valid for 24 hours (`expires_at`); `image.preview_url` is a short-lived signed link to the processed picture. `listing_fee` is in your billing currency (`currency`). If your billing currency cannot be billed right now, the preview still returns `S1`, with `listing_fee` `null` and `balance_sufficient` `false`, and publishing would return `E6`.\n\nE2: The image failed content moderation."
                    },
                    "400": {
                        "description": "E1: Missing or invalid input, including an image that is too large, too small or not a JPEG/PNG. The `message` says which.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "E8: Too many previews this hour. Wait and retry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Preview returned. `category` is what publishing this wording will get; `image.preview_token` is single-use, bound to your organisation and valid for 24 hours (`expires_at`); `image.preview_url` is a short-lived signed link to the processed picture. `listing_fee` is in your billing currency (`currency`). If your billing currency cannot be billed right now, the preview still returns `S1`, with `listing_fee` `null` and `balance_sufficient` `false`, and publishing would return `E6`.",
                    "E1": "Missing or invalid input, including an image that is too large, too small or not a JPEG/PNG. The `message` says which.",
                    "E2": "The image failed content moderation.",
                    "E8": "Too many previews this hour. Wait and retry."
                }
            }
        },
        "/events": {
            "post": {
                "operationId": "publishEvent",
                "summary": "Publish Event",
                "description": "Publishes one dated event. Sent as `multipart/form-data`. Publishing costs one flat price, deducted from your balance: **£10, converted into your organisation's billing currency at the day's European Central Bank reference rate**. The charge and the event are created together: if your balance is too low, nothing is created and nothing is charged. Listings are **non-refundable** once published, including if you later cancel. A recurring class is one event per date. **There is no `category_id`:** the category is determined from your title, description and venue name and returned in the response — preview it first if you want to see it before paying.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#publishEventSectionid"
                },
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "A unique value per event, for example a UUID. Retrying with the same key and the same fields returns the original response and never charges twice.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "description": "Up to 120 characters."
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 5000,
                                        "description": "Up to 5,000 characters."
                                    },
                                    "venue_name": {
                                        "type": "string",
                                        "description": "Example: `Bar Salsa`. Read, with the title and description, to determine the category."
                                    },
                                    "address": {
                                        "type": "string",
                                        "description": "Street address of the venue."
                                    },
                                    "city": {
                                        "type": "string",
                                        "description": "Example: `London`"
                                    },
                                    "country_code": {
                                        "type": "string",
                                        "description": "ISO 3166-1 alpha-2. Example: `GB` (not UK)."
                                    },
                                    "location": {
                                        "type": "array",
                                        "items": {
                                            "type": "number"
                                        },
                                        "maxItems": 2,
                                        "minItems": 2,
                                        "description": "Latitude first, then longitude, of the venue. Example: `51.5133`, `-0.1300`. **Coordinates are required and an address is not a substitute.** Every member sees how far the venue is from them, and that distance orders the list and drives the radius filter. `address` and `city` are shown to members but are never converted to coordinates on our side."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC only. Must be in the future and no more than 5 years ahead. Example: `2027-10-16T18:30:00Z`"
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC only. Must be after `starts_at`."
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "**Required.** The http(s) address of your own booking page. Members tap through to it to book; Agilis does not sell tickets. An event cannot be published without one."
                                    },
                                    "advertised_name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "The business name members see as “Listed by …” instead of your trading name. Up to 100 characters; must not start with http://, https:// or www.; no HTML or line breaks. Omit or send empty to show your trading name. You must be authorised by the business you name."
                                    },
                                    "price_min": {
                                        "type": "number",
                                        "description": "Ticket price, shown to members. Omit both to show no price (such events sort after priced ones when members sort by price). Send `0` for both to mark the event as free. Send the same value twice for a single price."
                                    },
                                    "price_max": {
                                        "type": "number",
                                        "description": "Ticket price, shown to members. Omit both to show no price (such events sort after priced ones when members sort by price). Send `0` for both to mark the event as free. Send the same value twice for a single price."
                                    },
                                    "currency": {
                                        "type": "string",
                                        "description": "Currency of the ticket price, one of [`GET /event-currencies`](https://www.agilis.dating/api-doc#eventCurrenciesSectionid). Required whenever a price is supplied. It describes the ticket price only and has no effect on what you are charged."
                                    },
                                    "image": {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                        "description": "JPG or PNG, detected from the file's content (not its name), up to **10 MB**, at least **1280 × 720** pixels. Members see events at 16:9: the image is scaled to fill a 16:9 frame with its centre kept and the overflow trimmed (a *centred cover crop*), never stretched or letterboxed. Pass `crop[x]`, `crop[y]`, `crop[w]` to choose the area yourself. If the area would be below 1280 × 720 the image is rejected rather than enlarged. Every image is decoded and re-encoded (so only a fresh copy is stored, with EXIF data including GPS removed), content-moderated, and scanned. Use `POST /events/preview` to see the result before paying."
                                    },
                                    "preview_token": {
                                        "type": "string",
                                        "description": "From `POST /events/preview`. Publishes exactly the image you previewed, with the crop you saw. Single-use."
                                    },
                                    "source_event_id": {
                                        "type": "integer",
                                        "description": "Reuse the image of one of your organisation's existing events, for example last week's class. The image is copied to the new event (not shared) and is not moderated again. Send `crop[]` on a later `PATCH` to re-frame it."
                                    },
                                    "crop[x": {
                                        "type": "integer",
                                        "description": "With `image` only: the 16:9 area to use. See Preview Event."
                                    },
                                    "crop[y": {
                                        "type": "integer",
                                        "description": "With `image` only: the 16:9 area to use. See Preview Event."
                                    },
                                    "crop[w": {
                                        "type": "integer",
                                        "description": "With `image` only: the 16:9 area to use. See Preview Event."
                                    },
                                    "payment_method": {
                                        "type": "string",
                                        "enum": [
                                            "B"
                                        ],
                                        "description": "`B` — pay from your balance. Payment by Stripe link is not available for events."
                                    },
                                    "environment": {
                                        "type": "string",
                                        "enum": [
                                            "TEST",
                                            "LIVE"
                                        ],
                                        "description": "`TEST` or `LIVE`. Must be your API key's own mode: a `pk_live_` key publishes LIVE events only, a `pk_test_` key TEST events only (HTTP 403 otherwise). A TEST event is validated, classified and moderated in full, including the balance check against your TEST balance, but is never charged, never invoiced and never shown to members."
                                    }
                                },
                                "required": [
                                    "title",
                                    "description",
                                    "venue_name",
                                    "address",
                                    "city",
                                    "country_code",
                                    "location",
                                    "starts_at",
                                    "ends_at",
                                    "url",
                                    "payment_method",
                                    "environment"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "S1: Event published. `amount_charged` and `currency` show what was taken from your balance, in your billing currency (0 for TEST); `category` is the category determined for it. A LIVE event appears in the app within a few minutes.\n\nE2: The image failed content moderation. Nothing was charged. Retry with the same Idempotency-Key and a different image.\n\nE3: Insufficient balance. Nothing was created. Top up in the Ad Portal and retry with the same Idempotency-Key."
                    },
                    "400": {
                        "description": "E1: Missing or invalid input: no `url`; no image source, or more than one; a `starts_at` in the past, `ends_at` before `starts_at`, or more than 5 years ahead; bad `country_code`; a price without a `currency`, or a currency not in `GET /event-currencies`; an image that is too large, too small, not a JPEG/PNG, or whose crop area is below 1280 × 720; an invalid, used or expired `preview_token`; a `source_event_id` that is not yours; an `advertised_name` over 100 characters, starting with http://, https:// or www., or containing HTML or a line break. The `message` says which.\n\nE6: Your organisation's billing currency cannot be billed right now. Nothing was created or charged. The message is either `Your organisation's currency (XYZ) is not one Agilis bills in. An Org Admin can choose a supported billing currency in the Ad Portal. You have not been charged. The event has not been created.` or `Prices in XYZ are temporarily unavailable because the exchange rate is out of date. Please try again later. You have not been charged. The event has not been created.`, with your currency code in place of XYZ.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "E7: LIVE publishing is temporarily unavailable. Nothing was created or charged. Retry later with the same Idempotency-Key.\n\nE9: Your organisation has not accepted the current Agilis Advertising Terms and Conditions. Nothing was created or charged. An Org Admin must accept them in the Ad Portal ([adportal.agilis.dating](https://adportal.agilis.dating)); then retry with the same Idempotency-Key. Editing, rescheduling, cancelling and deleting existing events are not affected.\n\nE1: `environment` is not your API key's mode. Nothing was created or charged.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "A request with this Idempotency-Key is still being processed."
                    },
                    "422": {
                        "description": "This Idempotency-Key was already used with different fields."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Event published. `amount_charged` and `currency` show what was taken from your balance, in your billing currency (0 for TEST); `category` is the category determined for it. A LIVE event appears in the app within a few minutes.",
                    "E1": "Missing or invalid input: no `url`; no image source, or more than one; a `starts_at` in the past, `ends_at` before `starts_at`, or more than 5 years ahead; bad `country_code`; a price without a `currency`, or a currency not in `GET /event-currencies`; an image that is too large, too small, not a JPEG/PNG, or whose crop area is below 1280 × 720; an invalid, used or expired `preview_token`; a `source_event_id` that is not yours; an `advertised_name` over 100 characters, starting with http://, https:// or www., or containing HTML or a line break. The `message` says which. / `environment` is not your API key's mode. Nothing was created or charged.",
                    "E2": "The image failed content moderation. Nothing was charged. Retry with the same Idempotency-Key and a different image.",
                    "E3": "Insufficient balance. Nothing was created. Top up in the Ad Portal and retry with the same Idempotency-Key.",
                    "E6": "Your organisation's billing currency cannot be billed right now. Nothing was created or charged. The message is either `Your organisation's currency (XYZ) is not one Agilis bills in. An Org Admin can choose a supported billing currency in the Ad Portal. You have not been charged. The event has not been created.` or `Prices in XYZ are temporarily unavailable because the exchange rate is out of date. Please try again later. You have not been charged. The event has not been created.`, with your currency code in place of XYZ.",
                    "E7": "LIVE publishing is temporarily unavailable. Nothing was created or charged. Retry later with the same Idempotency-Key.",
                    "E9": "Your organisation has not accepted the current Agilis Advertising Terms and Conditions. Nothing was created or charged. An Org Admin must accept them in the Ad Portal ([adportal.agilis.dating](https://adportal.agilis.dating)); then retry with the same Idempotency-Key. Editing, rescheduling, cancelling and deleting existing events are not affected."
                }
            },
            "get": {
                "operationId": "listEvents",
                "summary": "View Events",
                "description": "Returns events, newest first, with cursor pagination in the same envelope as `GET /offers`. **Who sees what:** an organisation admin's key sees every event in the organisation, whoever created it; a developer's key sees the whole organisation's events read-only; an advertiser's key sees its own. `attendees` is always a **band** (`<10`, `10-25`, `26-50`, `50+`), never an exact number: member privacy comes first, and an exact count on a small event would let attendance be inferred.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#viewEventsSectionid"
                },
                "parameters": [
                    {
                        "name": "environment",
                        "in": "query",
                        "required": true,
                        "description": "`test` or `live`. Case-insensitive. Must be your API key's own mode.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "test",
                                "live",
                                "TEST",
                                "LIVE"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Between 1 and 100. Default `20`.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "description": "The `next_cursor` from the previous page.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "event_status",
                        "in": "query",
                        "required": false,
                        "description": "One of `upcoming`, `scheduled`, `rescheduled`, `cancelled` or `ended`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "upcoming",
                                "scheduled",
                                "rescheduled",
                                "cancelled",
                                "ended"
                            ]
                        }
                    },
                    {
                        "name": "owner_user_id",
                        "in": "query",
                        "required": false,
                        "description": "Organisation admins: only the events created by this user.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "created_after",
                        "in": "query",
                        "required": false,
                        "description": "ISO 8601, UTC only.",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "created_before",
                        "in": "query",
                        "required": false,
                        "description": "ISO 8601, UTC only.",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Events returned successfully."
                    },
                    "400": {
                        "description": "Missing or invalid `environment`, `limit`, `cursor` or filter."
                    },
                    "401": {
                        "description": "Missing or invalid API key, or disabled account."
                    },
                    "403": {
                        "description": "`environment` is not your API key's mode."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/events/{event_id}": {
            "get": {
                "operationId": "getEvent",
                "summary": "View Event",
                "description": "One event: the same fields as the list, plus what it cost (`listing_price`, `billing_currency`, `invoice_id`), whether you may change it (`can_manage`, `can_delete`), whether members have interacted with it, the stored image's size and crop (`image_master`), and its `history`: every action taken on it, by whom and when.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#viewEventSectionid"
                },
                "parameters": [
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `3104`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Event returned."
                    },
                    "404": {
                        "description": "E1: The event was not found on this account (HTTP 404).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "E1": "The event was not found on this account (HTTP 404)."
                }
            },
            "patch": {
                "operationId": "editEvent",
                "summary": "Edit Event",
                "description": "Changes a published event, **free of charge**. Send only the fields to change. Editable: title, description, booking page, ticket price, venue and image. **Not dates** — use Reschedule. A wording change re-determines the category, which the response returns; preview first if you want to see it. A new image goes through the same checks as on publish and is stored at new URLs (invitations already sent keep the picture they were sent with). Members see the change within a few minutes. When uploading a file, send the request as `POST` with the header `X-HTTP-Method-Override: PATCH`, because file uploads need a POST body. **You remain responsible for telling everyone who booked through your own booking system** about any change; Agilis may notify its members but does not guarantee it.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#editEventSectionid"
                },
                "parameters": [
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `3104`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "url": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "advertised_name": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "venue_name": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "address": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "city": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "country_code": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "location": {
                                        "type": "string",
                                        "description": "Same rules as on publish. Changing the venue tells members who are going that the venue changed. Send `advertised_name` empty to go back to your trading name. Changing only the name does not change the category and notifies nobody."
                                    },
                                    "price_min": {
                                        "type": "string",
                                        "description": "A price change must send all three (all blank to show no price)."
                                    },
                                    "price_max": {
                                        "type": "string",
                                        "description": "A price change must send all three (all blank to show no price)."
                                    },
                                    "currency": {
                                        "type": "string",
                                        "description": "A price change must send all three (all blank to show no price)."
                                    },
                                    "image": {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                        "description": "A replacement picture. Same rules as on publish; moderated."
                                    },
                                    "preview_token": {
                                        "type": "string",
                                        "description": "Alternatives to `image`, as on publish."
                                    },
                                    "source_event_id": {
                                        "type": "string",
                                        "description": "Alternatives to `image`, as on publish."
                                    },
                                    "crop[x": {
                                        "type": "integer",
                                        "description": "On its own: re-frame the existing image from the stored original, no re-upload and no re-moderation. With `image`: the area of the new picture."
                                    },
                                    "crop[y": {
                                        "type": "integer",
                                        "description": "On its own: re-frame the existing image from the stored original, no re-upload and no re-moderation. With `image`: the area of the new picture."
                                    },
                                    "crop[w": {
                                        "type": "integer",
                                        "description": "On its own: re-frame the existing image from the stored original, no re-upload and no re-moderation. With `image`: the area of the new picture."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "S1: Event updated. `changed_fields` lists what changed; `category` is the category after the change; `venue_changed` says whether members will be told of a venue change.\n\nE2: A new image failed content moderation (nothing changed), or the event has ended or been cancelled and cannot be edited."
                    },
                    "400": {
                        "description": "E1: Invalid input; dates sent (use Reschedule); or nothing to change.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "E1: The event was not found on this account (HTTP 404).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Event updated. `changed_fields` lists what changed; `category` is the category after the change; `venue_changed` says whether members will be told of a venue change.",
                    "E1": "Invalid input; dates sent (use Reschedule); or nothing to change. / The event was not found on this account (HTTP 404).",
                    "E2": "A new image failed content moderation (nothing changed), or the event has ended or been cancelled and cannot be edited."
                }
            },
            "delete": {
                "operationId": "deleteEvent",
                "summary": "Delete Event",
                "description": "Removes an event that no member has interacted with yet, for example one published by mistake. Once any member has marked themselves as going, invited someone, or opened your booking page, the event can no longer be deleted: cancel it instead, so those members are told. Deleting does not return the listing fee.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#deleteEventSectionid"
                },
                "parameters": [
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `3104`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "S1: Event deleted.\n\nE5: Members have already interacted with this event. Use `POST /events/{event_id}/cancel`."
                    },
                    "404": {
                        "description": "E1: The event was not found on this account (HTTP 404).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Event deleted.",
                    "E1": "The event was not found on this account (HTTP 404).",
                    "E5": "Members have already interacted with this event. Use `POST /events/{event_id}/cancel`."
                }
            }
        },
        "/events/{event_id}/reschedule": {
            "post": {
                "operationId": "rescheduleEvent",
                "summary": "Reschedule Event",
                "description": "Moves a published event to a new date, at no charge. Within a few minutes the app shows the new date, and anyone who had accepted an invitation to the event is asked to confirm again, because nobody has agreed to the new date yet. **You are responsible for informing everyone who booked through your own booking system** of the change and the reason for it; Agilis may notify its members but does not guarantee it, and is not responsible for communication about your event. Use this rather than cancelling and publishing again.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#rescheduleEventSectionid"
                },
                "parameters": [
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `3104`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC only. In the future, no more than 5 years ahead."
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "ISO 8601, UTC only. After `starts_at`."
                                    }
                                },
                                "required": [
                                    "starts_at",
                                    "ends_at"
                                ]
                            },
                            "example": {
                                "starts_at": "2027-10-23T18:30:00Z",
                                "ends_at": "2027-10-23T23:00:00Z"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "S1: Event rescheduled.\n\nE2: The event has already ended or been cancelled and cannot be amended."
                    },
                    "400": {
                        "description": "E1: Invalid or unchanged dates.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "E1: The event was not found on this account (HTTP 404).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Event rescheduled.",
                    "E1": "Invalid or unchanged dates. / The event was not found on this account (HTTP 404).",
                    "E2": "The event has already ended or been cancelled and cannot be amended."
                }
            }
        },
        "/events/{event_id}/cancel": {
            "post": {
                "operationId": "cancelEvent",
                "summary": "Cancel Event",
                "description": "Cancels a published event. **Irreversible, and the listing fee is not refunded.** Within a few minutes the app marks it cancelled and every open or accepted invitation to it is cancelled. **You are responsible for informing everyone who booked through your own booking system**; Agilis may notify its members but does not guarantee it. Please cancel rather than leaving a listing up for an event that is not running, so nobody turns up to a closed door. No request body.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#cancelEventSectionid"
                },
                "parameters": [
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `3104`",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "S1: Event cancelled. The listing fee is not refunded.\n\nE2: The event has already ended or been cancelled."
                    },
                    "404": {
                        "description": "E1: The event was not found on this account (HTTP 404).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReturnCode"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                },
                "x-return-codes": {
                    "S1": "Event cancelled. The listing fee is not refunded.",
                    "E1": "The event was not found on this account (HTTP 404).",
                    "E2": "The event has already ended or been cancelled."
                }
            }
        },
        "/events/{event_id}/analytics": {
            "get": {
                "operationId": "getEventAnalytics",
                "summary": "View Event Analytics",
                "description": "Returns engagement for one event over the requested interval. Figures are refreshed every few minutes; `as_of` says when, and is `null` until the first member interaction.",
                "tags": [
                    "Events"
                ],
                "externalDocs": {
                    "url": "https://www.agilis.dating/api-doc#eventAnalyticsSectionid"
                },
                "parameters": [
                    {
                        "name": "event_id",
                        "in": "path",
                        "required": true,
                        "description": "Path parameter. Example: `3104`",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "interval",
                        "in": "query",
                        "required": true,
                        "description": "One of `24h`, `7d`, `30d`, `60d`, `90d` or `all`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "24h",
                                "7d",
                                "30d",
                                "60d",
                                "90d",
                                "all"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Analytics returned successfully."
                    },
                    "400": {
                        "description": "Missing or invalid `interval`."
                    },
                    "401": {
                        "description": "Missing or invalid API key, or disabled account."
                    },
                    "404": {
                        "description": "The event was not found on this account."
                    },
                    "500": {
                        "description": "Internal server error."
                    },
                    "429": {
                        "description": "Rate limit exceeded: wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "apiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "x-api-key",
                "description": "Created in the Ad Portal under Manage API Keys. Shown once; Roll key replaces a lost one. One key per mode (TEST or LIVE)."
            }
        },
        "schemas": {
            "ReturnCode": {
                "type": "object",
                "properties": {
                    "return_code": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "S1/S2 on success, E1–E9 on error. Meaning depends on the endpoint."
                    },
                    "message": {
                        "type": "string"
                    }
                }
            }
        }
    }
}