JSON:API Format

The Partners API follows the JSON:API specification (v1.1) for all request and response formatting.

Key Conventions

• Resource objects include type, id, and attributes
• Field names are dasherized (e.g., base-price instead of base_price)
• Resource types are pluralized (e.g., listings, users)

Content-Type

Requests should use the JSON:API media type:

Content-Type: application/vnd.api+json

The API also accepts application/json for backward compatibility.

Response Format

Single Resource

{
  "data": {
    "type": "listings",
    "id": "12345",
    "attributes": { ... }
  }
}

Collection

Collections include meta with pagination info and links for navigation (see Pagination):

{
  "data": [ ... ],
  "meta": { "pagination": { "count": 150, "page": 1, "pages": 6 } },
  "links": { "first": "...", "last": "...", "next": "...", "prev": null }
}

Error Response

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Listing 12345 not found",
      "source": {"pointer": null}
    }
  ]
}

See Error Handling for the full list of error codes and best practices.

Request Format (POST/PATCH)

When creating or updating resources, wrap the payload in a data object:

{
  "data": {
    "type": "users",
    "attributes": {
      "first-name": "John",
      "last-name": "Doe",
      "email": "john@example.com"
    }
  }
}

Compound Documents (Sideloading)

Some endpoints support including related resources in a single request using the ?include= parameter. This eliminates the need for multiple API calls.

GET /api/v1/listings/12345/?include=owner

Related resources appear in the top-level included array, with the relationship declared in relationships:

{
  "data": {
    "type": "listings",
    "id": "12345",
    "attributes": { ... },
    "relationships": {
      "owner": { "data": {"type": "users", "id": "789"} }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "789",
      "attributes": { ... }
    }
  ]
}

See each endpoint's documentation in the Swagger UI for the list of supported include values.

Pagination

Collection endpoints return paginated results. Use query parameters to control pagination, sorting, and filtering.

All collection endpoints use page-based pagination:

Parameter	Description	Default
page[number]	Page number (1-indexed)	1
page[size]	Items per page (max 100)	25

Responses include pagination info in meta and navigation links in links:

{
  "meta": {
    "pagination": {
      "count": 150,
      "page": 1,
      "pages": 6
    }
  },
  "links": {
    "first": "...?page%5Bnumber%5D=1",
    "last": "...?page%5Bnumber%5D=6",
    "next": "...?page%5Bnumber%5D=2",
    "prev": null
  }
}

Use the links URLs to navigate between pages without constructing URLs manually.

Sorting

Use the sort parameter with field names. Prefix with - for descending order. Multiple sort fields are comma-separated.

# Newest first
?sort=-created_at

# Multiple fields: by city ascending, then by price descending
?sort=city,-base_price

Each endpoint documents its own sortable fields in the Swagger UI.

Filtering

Use filter[field] parameters to narrow results.

# Single filter
?filter[enabled]=true

# Multiple filters
?filter[owner]=123&filter[enabled]=true

Each endpoint documents its own available filters in the Swagger UI.

Putting It All Together

Combine pagination, sorting, and filtering in a single request:

curl -X GET "$BASE_URL/api/v1/listings/?page[number]=1&page[size]=25&sort=-created_at&filter[enabled]=true" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/vnd.api+json"