Joinways Search API

openapi: 3.2.0
info:
  title: Joinways Public Search API
  version: 1.15.0
  description: 'The Joinways REST API lets you read and manage your CRM and event data:

    events, quotes, invoices, companies, contacts, leads (requests), venues,

    catalog, tasks, reports and more. It is a **JSON over HTTPS** API described by

    this OpenAPI 3.1 document, served at `https://joinways.app/openapi.yaml`

    and rendered at `https://joinways.app/docs/api`. The same data is reachable from AI assistants through the Joinways MCP

    server (`https://mcp.joinways.app`, guide at

    `https://joinways.app/docs/claude-mcp`): both surfaces share the OAuth

    server, the tokens, the scopes, the role permissions and the services of

    the app, so a rule holds the same way in the app, in the REST API and in

    MCP. ## Authentication


    Every request needs a **Bearer token** in the `Authorization` header:


    ```

    Authorization: Bearer jw_xxxxxxxx

    ```


    Two token types work:


    - **API key** (`jw_…`): an owner or admin creates one from **Settings →

    Developers → API keys** in the workspace (guide:

    `https://joinways.app/docs/api-keys`). An API key acts as the member

    who created it: it carries the read and write scopes, and the **role

    permissions its creator holds now** in the workspace (see below; a

    creator who leaves the workspace takes the key''s access with them). It

    does not expire unless you set an expiry, and can be revoked at any

    time from the same page. - **OAuth 2.1 access token** (`jw_oat_…`): for apps acting on a user''s

    behalf (Authorization Code + PKCE S256, same flow as the MCP server). - Authorization endpoint `https://joinways.app/oauth/authorize`, token

    endpoint `https://joinways.app/api/oauth/token`, revocation

    `https://joinways.app/api/oauth/revoke` (RFC 7009), metadata

    `https://joinways.app/.well-known/oauth-authorization-server`. - **Clients**: register with Dynamic Client Registration

    (`POST /api/oauth/register`), or use an https URL as `client_id`

    (Client ID Metadata Document). - **Resource** (RFC 8707): send `resource=https://joinways.app/api/v1`

    on the authorization and token requests to bind the token to this API

    (a token bound to `https://mcp.joinways.app` is refused here, and the

    other way round). An unknown resource is refused with

    `invalid_target`. Protected resource metadata:

    `https://joinways.app/.well-known/oauth-protected-resource/api/v1`. - **Refresh**: a client registered with the `refresh_token` grant gets a

    refresh token (`jw_ort_…`) next to a **1 hour** access token. Each

    refresh rotates the refresh token (the old one stops working); a

    refresh token unused for 90 days expires. A client without the

    refresh grant gets a **30 day** access token and re-runs the flow. A refresh may ask for fewer scopes: only the new access token is

    narrowed. A user who left the workspace gets `invalid_grant` on

    refresh, and the whole token family is revoked. - **Granted scope** = requested ∩ supported (`mcp.read`, `mcp.write`)

    ∩ registered by the client. - The authorization response carries `iss` (RFC 9207). The consent

    screen shows the host of a metadata-document client, and warns when

    the `redirect_uri` is on another domain. - A workspace owner sees and revokes connected apps in **Settings →

    Developers → MCP → Connected apps**. A token is **bound to a single workspace**. You never pass an

    `account_id`: the workspace comes from the token. The API is part of

    the **Pro plan and the free trial**: a valid token of a workspace

    without either is refused with `403 forbidden`, `details.reason:

    plan_not_eligible`. Revocation takes effect within about a minute

    across our infrastructure. Tokens are stored hashed (SHA-256) and shown

    once. A `401` carries the RFC 6750 / RFC 9728 challenge:


    ```

    WWW-Authenticate: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"

    ```


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `mcp.read` | Every `GET` |

    | `mcp.write` | Every `POST`, `PATCH`, `PUT`, `DELETE`, and reading (it implies `mcp.read`) |


    API keys carry both scopes.'
  contact:
    name: Joinways
    url: https://joinways.app
  license:
    name: Proprietary
  x-logo:
    url: /images/marketing/logo-header.svg
    altText: Joinways
    href: https://joinways.app
servers:
- url: https://joinways.app/api/v1
  description: Production
security:
- bearerAuth: []
- oauth2:
  - mcp.read
  - mcp.write
tags:
- name: Search
paths:
  /search:
    get:
      tags:
      - Search
      summary: Global search
      operationId: globalSearch
      description: Searches events, companies and people of the workspace (same engine as the app's search), best match first. Not paginated. **Role permission:** none (any member).
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.read
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: types
        in: query
        description: Keep only these result types (repeat the parameter or separate with commas).
        schema:
          type: array
          items:
            type: string
            enum:
            - event
            - company
            - person
        style: form
        explode: true
      - name: limit
        in: query
        description: Maximum results per type.
        schema:
          type: integer
          minimum: 1
          maximum: 30
          default: 15
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
        '400':
          $ref: '#/components/responses/BadRequest'
          description: '`q` is missing or longer than 100 characters, or `types` holds an unknown type.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  headers:
    RateLimitLimit:
      description: Requests allowed in the current window (per workspace once authenticated, per IP before).
      schema:
        type: integer
        example: 600
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 12
    RateLimitReset:
      description: When the window resets (ISO 8601).
      schema:
        type: string
        format: date-time
        example: '2026-10-04T14:31:00.000Z'
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 0
  schemas:
    SignedQuoteImportErrorReason:
      type: string
      description: POST /events/{id}/quotes/import.
      enum:
      - quotes_plan_required
      - event_not_found
      - quote_not_found
      - event_archived
      - quote_not_signable
      - duplicate_reference
      - invalid_pdf
      - invalid_amounts
      - pdf_too_large
      - forbidden
    LeadErrorReason:
      type: string
      description: 'Leads: convert, merge, link, status, create.'
      enum:
      - lead_not_found
      - lead_locked
      - invalid_venue
      - invalid_dates
      - venue_locked
      - venue_unavailable
      - lead_linked_elsewhere
      - same_lead
      - not_found
      - lead_archived
      - both_converted
      - target_archived
      - target_rejected
      - target_event_closed
      - other_venue_event
      - access_denied
      - event_not_found
      - event_closed
      - lead_moved_concurrently
      - validation_requires_event
      - lead_deleted
    PlatformErrorReason:
      type: string
      description: Authentication and rate limits (403, 429).
      enum:
      - plan_not_eligible
      - per-ip
      - per-account-minute
      - per-account-day
      - email_rate_limited
    SearchResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - event
          - company
          - person
        title:
          type: string
        subtitle:
          type:
          - string
          - 'null'
        highlighted_title:
          type:
          - string
          - 'null'
        highlighted_subtitle:
          type:
          - string
          - 'null'
        relevance_score:
          type: number
        event_start_date:
          type:
          - string
          - 'null'
          description: Events only.
        event_end_date:
          type:
          - string
          - 'null'
        event_status:
          type:
          - string
          - 'null'
        event_location:
          type:
          - string
          - 'null'
        event_location_color:
          type:
          - string
          - 'null'
        event_owner_name:
          type:
          - string
          - 'null'
        company_website:
          type:
          - string
          - 'null'
          description: Companies only.
    CatalogErrorReason:
      type: string
      description: 'Catalog writes, packages mostly. All `400` except `package_component` (`409`). `package_price_read_only`: the price and tax rate of a package come from its components, they are never sent (nor `pricing_mode` without `components`). `package_components_required`: a package needs at least one component (or `is_package: false`). `package_flag_required`: `components` sent for a plain item without `is_package: true`. `package_component_duplicate`: an item listed twice. `package_component_self`: the package among its own components. `package_component_not_found`: a component that is not an item of the package''s venue (unknown, another venue, another workspace). `package_component_is_package`: a package cannot contain a package. `package_component_vat_required`: a component has no tax rate and the venue no country to take one from. `package_price_zero`: the components add up to 0. `min_price_above_price`: `min_price` above the price of the package. `price_required`: a plain item (created, or a package turned back into one) without a price. `package_components_refused`: the database refused the composition (a rule above, lost to a concurrent change). `package_component` (409): the item is a component of a package; it cannot be deleted, nor become a package, before it is removed from that package.'
      enum:
      - package_price_read_only
      - package_components_required
      - package_flag_required
      - package_component_duplicate
      - package_component_self
      - package_component_not_found
      - package_component_is_package
      - package_component_vat_required
      - package_price_zero
      - min_price_above_price
      - price_required
      - package_components_refused
      - package_component
    EmailErrorReason:
      type: string
      description: POST /events/{id}/emails.
      enum:
      - event_not_found
      - event_archived
      - connection_not_found
      - connection_inactive
      - connection_cannot_send
      - no_connection
      - reconnect_required
      - email_rate_limited
    Error:
      type: object
      description: Standard error envelope returned on any non-2xx response.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code (see the Errors table).
              enum:
              - invalid_request
              - unauthorized
              - payment_required
              - forbidden
              - not_found
              - conflict
              - idempotency_conflict
              - payload_too_large
              - idempotency_key_reuse
              - quota_exceeded
              - rate_limited
              - server_error
              example: not_found
            message:
              type: string
              description: Human-readable message (do not parse it). Generic on 5xx.
              example: Event not found
            details:
              description: 'Structured details: field errors on validation (`formErrors`, `fieldErrors`), the query parameter at fault (`field`), `reason` (a stable code) on refusals, or `null`.'
              oneOf:
              - type: object
                additionalProperties: true
                properties:
                  reason:
                    $ref: '#/components/schemas/ErrorReason'
                  field:
                    type: string
                    description: The parameter or body field at fault.
              - type: 'null'
    QuoteErrorReason:
      type: string
      description: '409 state refusals, 400 validation (`min_price` with `details.params`; `package_article`: the line is an article of a package, write the package line; `package_discount_amount`: a package takes a percent discount only), 402 plan.'
      enum:
      - platform_quote_read_only
      - platform_quote_delete_forbidden
      - platform_version_signed
      - quote_conflict
      - quote_changed
      - quote_locked
      - quote_signed
      - quote_cancelled
      - quote_not_cancellable
      - quote_has_active_invoice
      - quote_has_amendments
      - quote_superseded
      - amendment_in_flight
      - amendment_nested
      - parent_not_active
      - parent_not_signed
      - parent_fully_invoiced
      - invalid_status
      - not_a_platform_version
      - event_closed
      - event_archived
      - platform_quote_no_document
      - min_price
      - invalid_location_item
      - package_article
      - package_discount_amount
      - no_fields
      - db_rule
      - validation
      - quotes_plan_required
    TaskErrorReason:
      type: string
      enum:
      - task_not_found
      - event_not_found
      - assignee_not_found
      - event_archived
      - no_fields
    ErrorReason:
      description: '`details.reason` of an error: snake_case lower case, the same value as the `code` of the matching MCP tool error. One list per domain.'
      anyOf:
      - $ref: '#/components/schemas/PlatformErrorReason'
      - $ref: '#/components/schemas/EventErrorReason'
      - $ref: '#/components/schemas/LeadErrorReason'
      - $ref: '#/components/schemas/TaskErrorReason'
      - $ref: '#/components/schemas/QuoteErrorReason'
      - $ref: '#/components/schemas/CatalogErrorReason'
      - $ref: '#/components/schemas/SignedQuoteImportErrorReason'
      - $ref: '#/components/schemas/EmailErrorReason'
    EventErrorReason:
      type: string
      description: Events, their sub-resources and the BEO.
      enum:
      - event_not_found
      - event_archived
      - event_not_archived
      - event_has_dependencies
      - venue_locked
      - venue_required
      - venue_unavailable
      - invalid_venue_spaces
      - invalid_dates
      - invalid_timezone
      - invalid_reference
      - invalid_assignee
      - invalid_stage
      - platform_duplicate
      - no_fields
      - revenue_access_required
      - version_conflict
  responses:
    Unauthorized:
      description: Missing, invalid, expired or revoked bearer token (`unauthorized`).
      headers:
        WWW-Authenticate:
          description: RFC 6750 challenge pointing at the protected resource metadata (RFC 9728).
          schema:
            type: string
          example: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid or expired token
              details: null
    RateLimited:
      description: 'Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests
              details:
                reason: per-account-minute
    BadRequest:
      description: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: Validation failed
              details:
                formErrors: []
                fieldErrors:
                  start_date:
                  - Required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth token
      description: 'Paste a token in the `Authorization: Bearer …` header: an **API key** (`jw_…`, created in Settings → Developers → API keys, acting with the role of the member who created it) or an **OAuth 2.1 access token** (`jw_oat_…`). A token is bound to a single workspace.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.1 authorization code grant with mandatory PKCE (S256). Access tokens are opaque strings prefixed `jw_oat_`, presented as `Authorization: Bearer …`: valid 1 hour with a refresh token (`jw_ort_…`, rotated on each use, 90 days idle), 30 days for a client without the refresh grant. Send `resource=https://joinways.app/api/v1` (RFC 8707). Clients register dynamically or use an https `client_id` (Client ID Metadata Document). Tokens are bound to a single workspace.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://joinways.app/oauth/authorize
          tokenUrl: https://joinways.app/api/oauth/token
          refreshUrl: https://joinways.app/api/oauth/token
          scopes:
            mcp.read: Read the workspace data the member's role can read.
            mcp.write: Create, update, delete and actions within the member's role (implies read).