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

# Create or replace a knowledge file

> Sends the file bytes directly as the request body. Do not wrap the
content in JSON or multipart form data. The extension and `Content-Type`
must describe the same supported file format. Send
`application/octet-stream` to infer the type from the extension.
The request body can contain at most 10 MiB (10,485,760 bytes).

A new path returns `201 Created`; replacing an existing path returns
`200 OK`. Use `If-Match` with the current metadata ETag to prevent a
concurrent update from being overwritten.




## OpenAPI

````yaml /api/openapi.yaml put /v1/knowledge/files/{file_path}
openapi: 3.1.0
info:
  title: Traversal API
  version: 1.0.0
  description: |
    The Traversal V1 API lets you launch investigations and manage the
    customer-authored knowledge files that agents use.

    All endpoints require a Bearer token. The authenticated user must have at
    least the `member` role within the organization unless an endpoint states
    otherwise.

    To wait for an investigation without polling, connect to
    `GET /v1/sessions/{session_id}/events`. The Server-Sent Events stream sends
    session status snapshots and closes when the session reaches a terminal
    status.
servers:
  - url: https://api.traversal.com
    description: Traversal API
security:
  - bearerAuth: []
tags:
  - name: Sessions
    description: Create, list, retrieve, and continue investigation sessions.
  - name: Knowledge Files
    description: List, upload, download, and delete customer-authored agent knowledge.
paths:
  /v1/knowledge/files/{file_path}:
    put:
      tags:
        - Knowledge Files
      summary: Create or replace a knowledge file
      description: |
        Sends the file bytes directly as the request body. Do not wrap the
        content in JSON or multipart form data. The extension and `Content-Type`
        must describe the same supported file format. Send
        `application/octet-stream` to infer the type from the extension.
        The request body can contain at most 10 MiB (10,485,760 bytes).

        A new path returns `201 Created`; replacing an existing path returns
        `200 OK`. Use `If-Match` with the current metadata ETag to prevent a
        concurrent update from being overwritten.
      operationId: upsertKnowledgeFile
      parameters:
        - $ref: '#/components/parameters/KnowledgeFilePath'
        - name: If-Match
          in: header
          required: false
          description: |
            Strong ETag from the current file metadata. The update returns
            `412 Precondition Failed` if the validator is stale. Use `*` to
            require that the path already exists.
          schema:
            type: string
        - name: If-None-Match
          in: header
          required: false
          description: |
            Send `*` to create the file only when the path does not already
            exist. If the path exists or is created concurrently, the request
            returns `412 Precondition Failed`.
          schema:
            type: string
      requestBody:
        required: true
        description: Raw file bytes, limited to 10 MiB (10,485,760 bytes).
        content:
          text/markdown:
            schema:
              type: string
              format: binary
          text/plain:
            schema:
              type: string
              format: binary
          text/csv:
            schema:
              type: string
              format: binary
          text/tab-separated-values:
            schema:
              type: string
              format: binary
          text/tsv:
            schema:
              type: string
              format: binary
          application/json:
            schema:
              type: string
              format: binary
          application/yaml:
            schema:
              type: string
              format: binary
          application/x-yaml:
            schema:
              type: string
              format: binary
          text/yaml:
            schema:
              type: string
              format: binary
          application/pdf:
            schema:
              type: string
              format: binary
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Existing knowledge file replaced.
          headers:
            ETag:
              schema:
                type: string
              description: Opaque version token for conditional requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeFileUpsert'
        '201':
          description: Knowledge file created.
          headers:
            ETag:
              schema:
                type: string
              description: Opaque version token for conditional requests.
            Location:
              schema:
                type: string
                format: uri
              description: URL of the created file metadata resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeFileUpsert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/ContentTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    KnowledgeFilePath:
      name: file_path
      in: path
      required: true
      description: |
        Slash-delimited path under `user_generated/` or `skills/`. Maximum
        length is 900 UTF-8 bytes, with at most 255 bytes per path segment.
      schema:
        type: string
      example: user_generated/runbooks/checkout.md
  schemas:
    KnowledgeFileUpsert:
      allOf:
        - $ref: '#/components/schemas/KnowledgeFile'
        - type: object
          required:
            - created
          properties:
            created:
              type: boolean
              description: True when this request created a new path.
    KnowledgeFile:
      type: object
      required:
        - path
        - content_type
        - size_bytes
        - sha256
        - etag
        - created_at
        - updated_at
      properties:
        path:
          type: string
          description: POSIX path under `user_generated/` or `skills/`.
          example: user_generated/runbooks/checkout.md
        content_type:
          type: string
          description: Stored media type.
          example: text/markdown
        size_bytes:
          type: integer
          minimum: 0
          description: File size in bytes.
        sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Hex SHA-256 digest of the file bytes.
        etag:
          type: string
          description: Opaque version token for conditional requests.
          example: '"d50c991679d03c2a7392b123eb748b4f"'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - conflict
                - internal
                - invalid_argument
                - not_found
                - payload_too_large
                - permission_denied
                - precondition_failed
                - resource_exhausted
                - unauthenticated
                - unavailable
                - unsupported_media_type
              description: Stable machine-readable error category.
            message:
              type: string
              description: Human-readable explanation of the error.
            retry_after:
              type: integer
              description: |
                Optional suggested seconds to wait before retrying. Present
                only when the server can recommend a delay, such as some `429`
                and `503` responses. When set, the response also includes a
                standard `Retry-After` HTTP header with the same value.
  responses:
    BadRequest:
      description: >-
        An invalid body, path, query parameter, or header value. The `message`
        identifies the failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: Authentication challenge (`Bearer`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient role, ownership, permission, or endpoint-specific access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >-
        The requested resource does not exist or is not visible to the
        authenticated organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MethodNotAllowed:
      description: >-
        The path exists but does not support the requested HTTP method. Uses the
        `invalid_argument` error code.
      headers:
        Allow:
          schema:
            type: string
          description: Comma-separated HTTP methods supported by the path.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: The request conflicts with the current resource state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PreconditionFailed:
      description: >-
        A conditional request validator is stale or its required resource does
        not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ContentTooLarge:
      description: The request body exceeds the endpoint limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: >-
        The request uses an unsupported file type, media type, or content
        encoding.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: >-
        API infrastructure is not available. Some responses include a
        recommended retry delay.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Suggested seconds to wait before retrying, when available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token in the `Authorization` header — for example,
        `Authorization: Bearer trv_ak_your_api_key_here`. Each key is bound to a
        specific user and organization.

````