> ## Documentation Index > Fetch the complete documentation index at: https://developers.safarapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Paginated adventure search > Search the Safariat catalog. Returned prices are the **net prices** for the partner (Safariat public price − Safariat margin ± negotiated partner margin). The bank then applies its own commission on its front end to compute the customer price. Pagination is cursor-based: pass the `cursor` received in `meta.next_cursor` to fetch the next page. No `next_cursor` → end of the result set. ## OpenAPI ````yaml /api-reference/openapi.yaml get /adventures openapi: 3.1.0 info: title: SafarAPI version: 1.0.0 summary: B2B API for banking partners — Safariat catalog and booking description: > SafarAPI lets banking partners integrate the Safariat travel catalog into their authenticated customer areas and book on behalf of their own end customers who are already authenticated and KYC-verified on the bank side. ## Channel model - The traveler never authenticates with Safariat. - Payment is collected on the banking platform (out-of-band from Safariat). - The bank submits the HMAC-signed payment confirmation at booking time. - Monthly post-payment settlement (see `GET /settlements`). ## Authentication Bearer API key in the `Authorization` header. Format `sk_live__` (production) or `sk_test__` (sandbox). The secret is shown only once at key generation — Safariat stores only an argon2id hash. ## Write request signing Production write requests (`POST`, `PUT`, `DELETE`) additionally require: - `X-Timestamp`: Unix timestamp in seconds, validity window ±5 minutes. - `X-Signature`: `hex(HMAC_SHA256(secret, "{timestamp}\n{method}\n{path}\n{body}"))`. - `Idempotency-Key`: opaque string unique per operation (UUID v4 recommended), retained for 24 h. Replayed responses carry an `Idempotent-Replayed: true` header. Request signing applies only to production `sk_live_*` keys. Sandbox `sk_test_*` keys are exempt from request signing: `X-Signature` and `X-Timestamp` are not required for writes in the sandbox (so the developer-portal "Try it" playground works end to end). `Idempotency-Key` is still required on writes in both environments. ## Error format All errors follow the `Error` schema with a stable i18n code, an English message, and the `request_id` for correlation with Safariat logs. ## Versioning URL-based versioning (`/v1`). No breaking changes within a version. Removals are announced 6 months in advance via the `Sunset` header (RFC 8594). ## Rate limiting Default limit of 600 req/min per key, contractually adjustable. The `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers are returned on every response. Exceeding the limit → `429 Too Many Requests` plus the `Retry-After` header. ## Sandbox An `sk_test_*` key targets the same infrastructure as production but isolates bookings in `test_mode=true`: no real email is sent, no settlement is issued, and webhooks are marked `test: true`. contact: name: SafarAPI Team email: api@safariat.ma url: https://developers.safariat.ma license: name: Proprietary — use subject to a signed partner agreement termsOfService: https://safariat.ma/legal/partner-terms servers: - url: https://api.safarapi.com/api/partner/v1 description: >- Production and sandbox share this host. The environment is selected by the API key prefix: sk_live_ targets production, sk_test_ targets the sandbox. security: - apiKey: [] tags: - name: Meta description: Metadata for the current key, service health. - name: Catalog description: Browsing the Safariat adventure catalog. - name: Quotes description: Price-locked quotes (30 min TTL) ahead of booking. - name: Bookings description: Creating, retrieving, and cancelling bookings. - name: Settlements description: Monthly Safariat → partner payout invoices. - name: Webhooks description: Managing endpoints that receive Safariat events. - name: Team description: Members of the partner console workspace and their roles. - name: Reviews description: Read-only access to traveler reviews on the Safariat catalog. - name: Files description: Presigned uploads for partner-supplied files (currently review photos). paths: /adventures: get: tags: - Catalog summary: Paginated adventure search description: > Search the Safariat catalog. Returned prices are the **net prices** for the partner (Safariat public price − Safariat margin ± negotiated partner margin). The bank then applies its own commission on its front end to compute the customer price. Pagination is cursor-based: pass the `cursor` received in `meta.next_cursor` to fetch the next page. No `next_cursor` → end of the result set. operationId: searchAdventures parameters: - $ref: '#/components/parameters/AcceptLanguage' - in: query name: query schema: type: string maxLength: 100 description: Full-text search on title / description / destination. - in: query name: type schema: $ref: '#/components/schemas/AdventureType' description: Filter on EXPERIENCE (short-duration) or TRIP (multi-day). - in: query name: category_codes schema: type: array items: type: string style: form explode: true description: >- One or more category codes (e.g. `trek`, `desert`, `cultural`). Repeat the parameter to combine. - in: query name: destination_locality schema: type: string maxLength: 100 description: Free-text locality match (city or area name, e.g. `marrakech`). - in: query name: agency_id schema: type: string format: uuid description: Restrict results to a single agency. - in: query name: date_from schema: type: string format: date description: Availability from this date (inclusive). - in: query name: date_to schema: type: string format: date description: Availability up to this date (inclusive). - in: query name: available_months schema: type: array maxItems: 12 items: type: string pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$ style: form explode: true description: >- One or more months in `YYYY-MM` format for flexible monthly availability. Up to 12 entries. - in: query name: participants schema: type: integer minimum: 1 maximum: 30 description: Total number of travelers (adults + children). - in: query name: price_min schema: type: number format: double minimum: 0 description: Minimum net price per traveler in MAD (inclusive). - in: query name: price_max schema: type: number format: double minimum: 0 description: >- Maximum net price per traveler in MAD (inclusive). Must be greater than or equal to `price_min`. - in: query name: duration_min_hours schema: type: integer minimum: 0 description: Minimum total adventure duration in hours. - in: query name: duration_max_hours schema: type: integer minimum: 0 description: >- Maximum total adventure duration in hours. Must be greater than or equal to `duration_min_hours`. - in: query name: rating_min schema: type: integer minimum: 1 maximum: 5 description: Minimum average customer rating (1-5). - in: query name: lat schema: type: number format: double minimum: -90 maximum: 90 description: >- Latitude of the reference point for geo-proximity search. Required if `lng` or `radius_km` is set. - in: query name: lng schema: type: number format: double minimum: -180 maximum: 180 description: >- Longitude of the reference point. Required if `lat` or `radius_km` is set. - in: query name: radius_km schema: type: number format: double exclusiveMinimum: 0 description: >- Search radius in kilometers from the reference point. Required if `lat` or `lng` is set. - in: query name: sort schema: type: string enum: - rating_desc - price_asc - price_desc - created_desc default: rating_desc description: > Sort order. Default `rating_desc` (best-rated first). Available options: - `rating_desc` — highest customer rating first - `price_asc` / `price_desc` — by base price (MAD) - `created_desc` — most recently added first - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' responses: '200': description: Page of results headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/AdventureSummary' meta: $ref: '#/components/schemas/PageMeta' example: data: - id: ad000002-0000-4000-8000-0000000000d2 slug: marrakech-3-jours-desert-sandbox type: TRIP title: '[DEMO] 3-day Sahara desert circuit from Marrakech' subtitle: null duration: days: 3 hours: 0 minutes: 0 cover_image_url: https://placehold.co/600x400?text=DEMO destinations: - Marrakech categories: - desert price_from: amount: '2400.00' currency: MAD rating: average: 4.7 count: 23 agency: id: 1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f name: Sahara Demo Trekking meta: count: 1 next_cursor: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: AcceptLanguage: in: header name: Accept-Language required: false schema: type: string enum: - fr - en - ar default: fr description: Language of the returned labels (titles, descriptions, categories). Cursor: in: query name: cursor required: false schema: type: string maxLength: 256 description: > Opaque pagination cursor returned by the previous response in `meta.next_cursor`. Pass `null`/omit on the first request; absence of `next_cursor` in the response signals the last page. Treat the cursor as fully opaque — its format is internal and may evolve. **Keyset pagination (all listing endpoints except `/adventures`).** The cursor is anchored on the last row of the previous page, so results are **stable under concurrent writes** — no duplicates, no skipped rows when items are inserted between page fetches. Two cursors are not interchangeable across endpoints: a cursor obtained from `/reviews` will be rejected with `400` on `/bookings`. **`/adventures` is offset-based by design** (dynamic sort: popularity, price, distance) and will not migrate to keyset. Its cursor cannot be passed to other endpoints. **Behavior change (Phase B):** `/webhooks/deliveries` now sorts by `created_at` instead of `updated_at`. The previous sort field is mutable (retry attempts), which is incompatible with the keyset invariant. Use the `status` filter to surface deliveries currently being retried (`status=PENDING,FAILED`). Limit: in: query name: limit required: false schema: type: integer minimum: 1 maximum: 100 default: 25 description: Maximum number of items per page. schemas: AdventureType: type: string enum: - EXPERIENCE - TRIP description: | - `EXPERIENCE`: short adventure (a few hours to 1 day), hourly slots. - `TRIP`: multi-day tour with an itinerary. AdventureSummary: type: object required: - id - slug - type - title - duration - cover_image_url - price_from - rating properties: id: type: string format: uuid slug: type: string example: marrakech-3-jours-desert-sandbox type: $ref: '#/components/schemas/AdventureType' title: type: string subtitle: type: string nullable: true duration: type: object properties: days: type: integer minimum: 0 hours: type: integer minimum: 0 minutes: type: integer minimum: 0 cover_image_url: type: string format: uri cover_image_blurhash: type: string nullable: true description: >- Compact placeholder (BlurHash) for instant rendering before the cover image loads. cover_image_variants: type: object nullable: true description: Responsive variant URLs of the cover image. properties: small: type: string format: uri nullable: true medium: type: string format: uri nullable: true destinations: type: array items: type: string description: Main destination labels. categories: type: array items: type: string price_from: $ref: '#/components/schemas/Money' pricing: $ref: '#/components/schemas/PartnerPricing' description: Indicative revenue breakdown on `price_from` (`indicative = true`). rating: type: object properties: average: type: number format: float minimum: 0 maximum: 5 count: type: integer minimum: 0 agency: type: object nullable: true description: >- Owning agency. `name` may be null if the agency record was deleted between indexing and read. properties: id: type: string format: uuid name: type: string nullable: true availability_hint: type: string nullable: true enum: - AVAILABLE - FEW_LEFT - SOLD_OUT description: | Computed at search-time from booking ratios. Surfaces UI badges ("plus que 2 places", "complet"). Null if no signal available. distance_km: type: number format: double nullable: true minimum: 0 description: > Haversine distance between the search reference point (`lat`/`lng` query params) and the adventure's primary location. Null if the search was not geo-anchored. PageMeta: type: object required: - count properties: count: type: integer description: Number of items in the current page. example: 25 next_cursor: type: string nullable: true description: >- Cursor to pass as the `cursor` parameter for the next page. `null` = last page. Money: type: object required: - amount - currency properties: amount: type: string pattern: ^-?\d+\.\d{2}$ description: Amount as a decimal string with 2 decimals to preserve precision. example: '3200.00' currency: type: string enum: - MAD description: Currency — MAD only in V1. example: MAD PartnerPricing: type: object description: > Revenue breakdown for the AWB channel, in MAD. Canonical home for all partner-facing amounts. On catalog (search / adventure detail) and quote responses `indicative` is `true` and `sandbox_surcharge` is `0` (the bank sets its surcharge at booking time), so `customer_price` equals `b2c_price`. On booking responses `indicative` is `false` and the values reflect the amounts actually recorded. Invariant: `amount_due_to_safariat + awb_commission_share + sandbox_surcharge = customer_price`. required: - b2c_price - customer_price - amount_due_to_safariat - awb_commission_share - sandbox_surcharge - indicative properties: b2c_price: $ref: '#/components/schemas/Money' description: Public B2C reference price (price floor guaranteed to the customer). customer_price: $ref: '#/components/schemas/Money' description: >- Total price paid by the customer = `b2c_price + sandbox_surcharge`. Equals `b2c_price` before booking. amount_due_to_safariat: $ref: '#/components/schemas/Money' description: >- Net reversed to Safariat = operator share + 65% of the base commission (the daily wire amount). awb_commission_share: $ref: '#/components/schemas/Money' description: AWB's 35% share of the base commission. sandbox_surcharge: $ref: '#/components/schemas/Money' description: >- AWB's own surcharge (100% AWB), derived as `customer_price − b2c_price`. `0` before booking. indicative: type: boolean description: > `true` for catalog/quote "from" prices (final amounts confirmed at booking); `false` on booking responses. Error: type: object required: - code - message - request_id properties: code: type: string description: | Stable, documented i18n code. Form `domain.subdomain.detail` (e.g. `payment.amount.mismatch`, `auth.api_key.invalid`). example: validation.required.field message: type: string description: >- English message (for bank logs). API errors are never localized on the Safariat side. example: Field 'rate_pack_id' is required. request_id: type: string description: Unique request ID on the Safariat side. details: type: object description: Optional structured details (offending field, expected value, etc.). additionalProperties: true headers: XRequestId: schema: type: string format: uuid description: >- Unique request ID on the Safariat side. Provide it to support in case of an incident. XRateLimitRemaining: schema: type: integer description: Requests remaining in the current window. RetryAfter: schema: type: integer description: Seconds to wait before the next attempt (RFC 7231). XRateLimitLimit: schema: type: integer description: Request limit per minute for the current key. XRateLimitReset: schema: type: integer format: int64 description: Unix timestamp (s) at which the window resets. responses: BadRequest: description: Malformed request (syntactic validation). content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingField: value: code: validation.required.field message: Field 'rate_pack_id' is required. request_id: 01HXY2ZRPM3R8K9PSBTRQYNFHC Unauthorized: description: API key missing, invalid, expired, or incorrect HMAC signature. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing: value: code: auth.api_key.missing message: Authorization header is required. request_id: 01HXY2ZRPM3R8K9PSBTRQYNFHC invalid: value: code: auth.api_key.invalid message: The provided API key is invalid or has been revoked. request_id: 01HXY2ZRPM3R8K9PSBTRQYNFHC signatureInvalid: value: code: auth.signature.invalid message: HMAC signature does not match. request_id: 01HXY2ZRPM3R8K9PSBTRQYNFHC timestampSkew: value: code: auth.timestamp.skew message: Timestamp is more than 5 minutes off server time. request_id: 01HXY2ZRPM3R8K9PSBTRQYNFHC TooManyRequests: description: Rate limit exceeded for the current key. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit.exceeded message: Rate limit exceeded for this API key. request_id: 01HXY2ZRPM3R8K9PSBTRQYNFHC securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sk_live__ or sk_test__ x-default: sk_test_DEMO0000_replace_with_your_sandbox_key description: > API key authentication. Issued by the Safariat admin or via the partner portal. The secret is shown only once at generation. Production `sk_live_*` keys must additionally sign every write request (`POST`/`PUT`/`DELETE`) with the `X-Timestamp` and `X-Signature` headers. Sandbox `sk_test_*` keys are exempt from request signing: `X-Signature` and `X-Timestamp` are not required for writes in the sandbox (so the developer-portal "Try it" playground works end to end). The `Idempotency-Key` header remains required on writes in both environments. ````