Tettra Teams API

openapi: 3.1.0
info:
  title: Tettra REST Teams API
  description: A limited experimental REST API for automating common Tettra tasks and building custom integrations. Supports creating pages, searching the knowledge base, suggesting new pages, suggesting page updates, and submitting questions. All endpoints require an API key available on Scaling and Enterprise plans.
  version: 1.0.0
  contact:
    url: https://support.tettra.com/api-overview
  termsOfService: https://tettra.com/terms/
servers:
- url: https://app.tettra.co/api
  description: Tettra API
security:
- apiKey: []
tags:
- name: Teams
paths:
  /teams/{team_id}/search:
    get:
      operationId: searchPages
      summary: Search pages
      description: Search for pages in the Tettra knowledge base. Results are ranked by page title matches, header matches (H1–H3), and page content. Returns up to 5 results. Omitting the query parameter returns the most recent pages.
      parameters:
      - name: team_id
        in: path
        required: true
        description: The identifier for the Tettra team.
        schema:
          type: string
      - name: api_key
        in: query
        required: true
        description: Your Tettra API key for authentication.
        schema:
          type: string
      - name: query
        in: query
        required: false
        description: The search term to query the knowledge base. If omitted, the most recent pages are returned.
        schema:
          type: string
      responses:
        '200':
          description: Successful search response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized – invalid or missing API key.
        '404':
          description: Team not found.
      tags:
      - Teams
  /teams/{team_id}/questions:
    post:
      operationId: createQuestion
      summary: Create a question
      description: Publish a new question to the Tettra knowledge base. The API key determines the asker of the question. Questions can optionally be assigned to specific users and organized under a category or subcategory.
      parameters:
      - name: team_id
        in: path
        required: true
        description: The identifier for the Tettra team.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuestionRequest'
      responses:
        '200':
          description: Question created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateQuestionResponse'
        '401':
          description: Unauthorized – invalid or missing API key.
        '404':
          description: Team not found.
        '422':
          description: Validation error – missing required fields or invalid values.
      tags:
      - Teams
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the category.
        name:
          type: string
          description: Name of the category.
        url:
          type: string
          format: uri
          description: URL of the category in Tettra.
    CreateQuestionResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the question was created successfully.
        question:
          type: object
          description: The created question object.
          properties:
            id:
              type: integer
              description: Unique identifier for the created question.
            title:
              type: string
              description: Title of the question.
            url:
              type: string
              format: uri
              description: URL of the question in Tettra.
    SearchResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the search request was successful.
        query:
          type: string
          description: The search term that was used.
        pages:
          type: array
          description: Array of up to 5 matching page results.
          items:
            $ref: '#/components/schemas/PageResult'
    CreateQuestionRequest:
      type: object
      required:
      - api_key
      - title
      properties:
        api_key:
          type: string
          description: Your Tettra API key. This determines the asker of the question.
        title:
          type: string
          description: The title of the question.
        details:
          type: string
          description: Additional details about the question, formatted as HTML.
        category_id:
          type: integer
          description: Category identifier for organizing the question.
        subcategory_id:
          type: integer
          description: Subcategory identifier. If provided, must belong to the specified category_id.
        assignees:
          type: array
          description: Array of user IDs to assign the question to.
          items:
            type: integer
    PageResult:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the page.
        title:
          type: string
          description: Title of the page.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the page was last updated.
        url:
          type: string
          format: uri
          description: URL of the page in Tettra.
        content:
          type: string
          description: Text content of the page.
        owner:
          type: object
          description: The user who owns the page.
          properties:
            id:
              type: integer
              description: User identifier.
            name:
              type: string
              description: Display name of the page owner.
        category:
          $ref: '#/components/schemas/Category'
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: api_key
      description: API key for authentication. Available on Scaling and Enterprise plans. Determines the acting user for operations such as creating questions.