> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tikk.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# List your services

> Lists your services of one type, paginated. Without `type` you get your
default services: the ones visitors can book right now, which means
active and within your plan's service limit, with the `is_default` one
first. Single-use services are listed newest first, whatever their
status.

**Scope:** `services.read`


Every service has a `type`:

| `type` | What it is |
| - | - |
| `default` | A permanent booking page, such as "Intro call". |
| `single_use` | A private booking link for one person, spent once it's booked. Bookings through it are accepted and never paid. |

<Note>
  Don't confuse `type: "default"` with `is_default`. `is_default` marks the one
  service your booking page highlights.
</Note>


## OpenAPI

````yaml api-reference/openapi.yaml GET /services
openapi: 3.1.0
info:
  title: Tikk API
  version: 1.0.0
  summary: Your Tikk profile, services, free time slots and bookings.
  description: |
    A REST API over one Tikk account: its public profile, its services, the
    time slots it has free and the bookings people have made with it. Reading
    is the default; writing is limited to services.

    Every response is JSON, every timestamp is ISO 8601 in UTC, and every
    request needs a bearer token: an API key (`tikk_sk_...`) or an OAuth access
    token. Each endpoint requires one scope. Rate limit: 60 requests per minute
    per credential.
  contact:
    name: Tikk support
    url: https://tikk.chat
servers:
  - url: https://app.tikk.chat/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Profile
    description: Your public profile and plan.
  - name: Services
    description: Your default services and single-use links.
  - name: Availability
    description: The time slots you have free.
  - name: Bookings
    description: The bookings people have made with you.
paths:
  /services:
    get:
      tags:
        - Services
      summary: List your services
      description: |
        Lists your services of one type, paginated. Without `type` you get your
        default services: the ones visitors can book right now, which means
        active and within your plan's service limit, with the `is_default` one
        first. Single-use services are listed newest first, whatever their
        status.

        **Scope:** `services.read`
      operationId: listServices
      parameters:
        - name: type
          in: query
          required: false
          description: Which type of service to list.
          schema:
            type: string
            enum:
              - default
              - single_use
            default: default
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A page of services.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceCollection'
              examples:
                default:
                  summary: Default services
                  value:
                    data:
                      - type: default
                        id: 48213
                        slug: intro-call
                        title: Intro call
                        description: A first chat to see if we're a fit.
                        is_default: true
                        is_group: false
                        max_attendees: null
                        requires_approval: true
                        durations:
                          - minutes: 30
                            price: null
                            currency: EUR
                          - minutes: 60
                            price: 7500
                            currency: EUR
                        location:
                          type: video
                          label: Video Meeting
                          address: null
                        embed_url: https://tikk.chat/jane/intro-call
                    links:
                      first: https://app.tikk.chat/api/v1/services?page=1
                      last: https://app.tikk.chat/api/v1/services?page=1
                      prev: null
                      next: null
                    meta:
                      current_page: 1
                      from: 1
                      last_page: 1
                      links: []
                      path: https://app.tikk.chat/api/v1/services
                      per_page: 25
                      to: 1
                      total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MissingScope'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth:
            - services.read
components:
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: Results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    Page:
      name: page
      in: query
      required: false
      description: Page to return.
      schema:
        type: integer
        minimum: 1
        default: 1
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per minute for this credential.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
        example: 59
  schemas:
    ServiceCollection:
      type: object
      properties:
        data:
          type: array
          description: Services of the requested type.
          items:
            $ref: '#/components/schemas/Service'
        links:
          $ref: '#/components/schemas/PaginationLinks'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - data
        - links
        - meta
    Service:
      oneOf:
        - $ref: '#/components/schemas/DefaultService'
        - $ref: '#/components/schemas/SingleUseService'
      discriminator:
        propertyName: type
        mapping:
          default:
            $ref: '#/components/schemas/DefaultService'
          single_use:
            $ref: '#/components/schemas/SingleUseService'
    PaginationLinks:
      type: object
      properties:
        first:
          type:
            - string
            - 'null'
          format: uri
        last:
          type:
            - string
            - 'null'
          format: uri
        prev:
          type:
            - string
            - 'null'
          format: uri
          description: '`null` on the first page.'
        next:
          type:
            - string
            - 'null'
          format: uri
          description: '`null` on the last page.'
      required:
        - first
        - last
        - prev
        - next
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        from:
          type:
            - integer
            - 'null'
          description: Position of the first result on this page.
          example: 1
        last_page:
          type: integer
          example: 4
        links:
          type: array
          description: Numbered pager links, for building a page-number UI.
          items:
            type: object
            properties:
              url:
                type:
                  - string
                  - 'null'
                format: uri
              label:
                type: string
              active:
                type: boolean
        path:
          type: string
          format: uri
          description: The endpoint URL without query parameters.
        per_page:
          type: integer
          example: 25
        to:
          type:
            - integer
            - 'null'
          description: Position of the last result on this page.
          example: 25
        total:
          type: integer
          description: Results across all pages.
          example: 87
      required:
        - current_page
        - from
        - last_page
        - links
        - path
        - per_page
        - to
        - total
    Error:
      type: object
      properties:
        message:
          type: string
          description: What went wrong. Branch on the status code, not on this text.
      required:
        - message
    MissingScopeError:
      type: object
      properties:
        message:
          type: string
          example: Missing required scope.
        scopes:
          type: array
          description: The scope or scopes the endpoint needs.
          items:
            type: string
      required:
        - message
        - scopes
    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: The to field must be a date after or equal to from.
        errors:
          type: object
          description: Failed rules, keyed by parameter name.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            to:
              - The to field must be a date after or equal to from.
      required:
        - message
        - errors
    DefaultService:
      title: Default service
      type: object
      description: A permanent booking page, such as "Intro call".
      properties:
        type:
          type: string
          const: default
        id:
          type: integer
          description: >-
            Pass it to `/services/{id}`, as `service` on `/availability`, and as
            `service` on `POST /services` to copy it into a single-use service.
          example: 48213
        slug:
          type: string
          description: The last segment of the service's booking URL.
          example: intro-call
        title:
          type: string
          example: Intro call
        description:
          type:
            - string
            - 'null'
          description: Shown on the booking page.
        is_default:
          type: boolean
          description: >-
            `true` for the one service your booking page highlights. Not the
            same as `type: default`.
        is_group:
          type: boolean
          description: '`true` if several people can book the same slot.'
        max_attendees:
          type:
            - integer
            - 'null'
          description: Seat cap for a group service. `null` otherwise.
        requires_approval:
          type: boolean
          description: '`true` if you accept each booking by hand.'
        durations:
          type: array
          description: The durations a booker can pick.
          items:
            $ref: '#/components/schemas/Duration'
        location:
          oneOf:
            - $ref: '#/components/schemas/ServiceLocation'
            - type: 'null'
          description: Where the meeting takes place.
        embed_url:
          type:
            - string
            - 'null'
          format: uri
          description: The service's booking URL. `null` until you pick a username.
          example: https://tikk.chat/jane/intro-call
      required:
        - type
        - id
        - slug
        - title
        - description
        - is_default
        - is_group
        - max_attendees
        - requires_approval
        - durations
        - location
        - embed_url
    SingleUseService:
      title: Single-use service
      type: object
      description: >-
        A private booking link for one person, spent once it's booked. Bookings
        made through one are accepted straight away and never paid.
      properties:
        type:
          type: string
          const: single_use
        id:
          type: integer
          description: >-
            Pass it to `GET` and `DELETE /services/{id}`, and as `service` on
            `/availability`.
          example: 73920
        title:
          type: string
          description: Name of the link.
          example: Intro call for Sam Smith
        description:
          type:
            - string
            - 'null'
          description: Note shown at the top of the booking page.
        status:
          type: string
          enum:
            - open
            - used
            - expired
            - disabled
          description: |
            `open` can be booked. `used` has been booked and no longer works.
            `expired` passed `expires_at` without a booking. `disabled` was
            switched off in Tikk. A used link stays `used`, even after it
            expires or is switched off.
          example: open
        url:
          type:
            - string
            - 'null'
          format: uri
          description: The private link to send. `null` until you pick a username.
          example: https://tikk.chat/jane/Xk3pQ9aB2c/intro-call-for-sam-smith
        contact:
          oneOf:
            - $ref: '#/components/schemas/Person'
            - type: 'null'
          description: Who the link is for. `null` when no contact was given.
        durations:
          type: array
          description: The offered durations.
          items:
            $ref: '#/components/schemas/Duration'
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the link stops working.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - type
        - id
        - title
        - description
        - status
        - url
        - contact
        - durations
        - expires_at
        - created_at
    Duration:
      type: object
      properties:
        minutes:
          type: integer
          description: Length in minutes.
          example: 30
        price:
          type:
            - integer
            - 'null'
          description: >-
            Price in minor currency units, so `7500` is €75.00. `null` when
            free. Always `null` on single-use services, which are never paid.
          example: 7500
        currency:
          type: string
          description: ISO 4217 code. Always `EUR`.
          example: EUR
      required:
        - minutes
        - price
        - currency
    ServiceLocation:
      type: object
      properties:
        type:
          type: string
          enum:
            - video
            - in_person
            - none
          example: video
        label:
          type: string
          description: Human-readable name of the location type.
          example: Video Meeting
        address:
          type:
            - string
            - 'null'
          description: Only when you show the address publicly. `null` otherwise.
      required:
        - type
        - label
        - address
    Person:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          example: Sam Smith
        email:
          type:
            - string
            - 'null'
          format: email
          example: sam@example.com
      required:
        - name
        - email
  responses:
    Unauthorized:
      description: No credential was sent, or it's revoked, expired or unknown.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthenticated.
    MissingScope:
      description: The credential doesn't carry the scope this endpoint needs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MissingScopeError'
          examples:
            missingScope:
              $ref: '#/components/examples/MissingScope'
    ValidationFailed:
      description: One or more parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    TooManyRequests:
      description: More than 60 requests in a minute for this credential.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Too Many Attempts.
  examples:
    MissingScope:
      summary: Missing scope
      value:
        message: Missing required scope.
        scopes:
          - services.write
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        An API key from **Settings → API Keys** (starts with `tikk_sk_`), or an
        OAuth access token for a partner app. Both carry scopes; each endpoint
        lists the one it needs.

````