Matter Account API

openapi: 3.2.0
info:
  title: Matter Account API
  version: '1.0'
  description: 'The Matter API lets you read, save, and organize content in your Matter library.


    Every request requires a [Bearer token](/api/authentication) and an active

    Matter Pro subscription.

    '
  contact:
    email: hello@getmatter.com
    url: https://getmatter.com
servers:
- url: https://api.getmatter.com/public
  description: Production
security:
- bearerAuth: []
tags:
- name: Account
  description: Your user profile and API quota.
paths:
  /v1/me:
    get:
      operationId: getMe
      summary: Get current account
      description: Returns the authenticated user's account information and rate-limit quota.
      tags:
      - Account
      responses:
        '200':
          description: Account info.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              example:
                object: account
                id: act_k8x2m
                name: Jane Smith
                email: jane@example.com
                rate_limit:
                  read: 120
                  write: 30
                  save: 10
                  search: 30
                  markdown: 20
                  burst: 5
                created_at: '2024-06-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Retry after 12 seconds.
    ProRequired:
      description: Active Matter Pro subscription required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: pro_required
              message: A Matter Pro subscription is required to use the API.
    Unauthorized:
      description: Invalid or missing API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: authentication_required
              message: A valid API token is required.
  headers:
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) when the window resets.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Maximum requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
            field:
              type: string
              description: The request field that caused the error, if applicable.
    Account:
      type: object
      required:
      - object
      - id
      - name
      - email
      - rate_limit
      - created_at
      properties:
        object:
          type: string
          const: account
        id:
          type: string
          description: Prefixed account ID (e.g. `act_k8x2m`).
          example: act_k8x2m
        name:
          type: string
          example: Jane Smith
        email:
          type: string
          format: email
          example: jane@example.com
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
        created_at:
          type: string
          format: date-time
          example: '2024-06-15T10:30:00Z'
    RateLimit:
      type: object
      description: Per-minute quotas (except burst which is per-second).
      required:
      - read
      - write
      - save
      - markdown
      - burst
      properties:
        read:
          type: integer
          description: GET requests per minute.
          example: 120
        write:
          type: integer
          description: POST/PATCH/DELETE requests per minute.
          example: 30
        save:
          type: integer
          description: POST /v1/items per minute.
          example: 10
        search:
          type: integer
          description: GET /v1/search per minute.
          example: 30
        markdown:
          type: integer
          description: GET with `?include=markdown` per minute.
          example: 20
        burst:
          type: integer
          description: All requests per second.
          example: 5
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Personal API token with `mat_` prefix. Generate one at https://web.getmatter.com/settings.

        '