Kosli API

openapi: 3.1.0
info:
  title: Kosli API
  version: '2026-10-29'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-29: 10 operation(s) read from 10 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Kosli has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 8
    pages-with-code: 10
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-29'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://app.kosli.com/api/v2/openapi.json
  - https://docs.kosli.com/api-reference/flows/get-flow.md
  - https://docs.kosli.com/policy-reference/rego_policy.md
  - https://docs.kosli.com/api-reference/flows/list-flows.md
  - https://docs.kosli.com/api-reference/repos/get-a-repo.md
  - https://docs.kosli.com/api-reference/repos/list-repos.md
  - https://docs.kosli.com/api-reference/trails/get-trail.md
  - https://docs.kosli.com/api-reference/flows/rename-flow.md
  - https://docs.kosli.com/api-reference/actions/get-action.md
  - https://docs.kosli.com/api-reference/builds/list-builds.md
paths:
  /actions/{org}/{actionNumber}:
    get:
      operationId: get_actions_org_actionNumber
      tags:
      - Actions
      summary: Get action
      description: Get a specific action for an org.
      x-source: https://docs.kosli.com/api-reference/actions/get-action.md
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: actionNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetActionsOrgActionnumberResponse'
      x-evidence:
        kind: documentation
  /api/v2/environments/{yourorgname}:
    get:
      operationId: get_api_v2_environments_yourorgname
      tags:
      - Api
      summary: GET /api/v2/environments/{yourOrgName}
      x-source: https://app.kosli.com/api/v2/openapi.json
      parameters:
      - name: yourorgname
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2EnvironmentsYourorgnameResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl example\n\n```shell\ncurl -H \"Authorization: Bearer <<your-api-key>>\" https://app.kosli.com/api/v2/environments/<<your-org-name>>\n```\n","version":"2.0"},"paths":{"/actions/{org}":{"get":{"tags":["Actions"],"summary":"List
          actions","description":"List actions for an org.","operationId":"list_actions","security":[{"HTTPBearer":[]},{"HTTPBasic":[]}],"parameters":[{"name":"org","in":"path","r'
  /api/v2/trails/$ORG/$FLOW/$TRAIL_NAME/moments/latest:
    get:
      operationId: get_api_v2_trails_ORG_FLOW_TRAIL_NAME_moments_latest
      tags:
      - Api
      summary: GET /api/v2/trails/$ORG/$FLOW/$TRAIL_NAME/moments/latest
      x-source: https://docs.kosli.com/policy-reference/rego_policy.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -H "Authorization: Bearer $KOSLI_API_TOKEN"  "https://app.kosli.com/api/v2/trails/$ORG/$FLOW/$TRAIL_NAME/moments/latest"

          ```'
  /attestations/{org}/uploads:
    post:
      operationId: post_attestations_org_uploads
      tags:
      - Attestations
      summary: Create an attachment upload
      x-source: https://app.kosli.com/api/v2/openapi.json
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAttestationsOrgUploadsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAttestationsOrgUploadsResponse'
      x-evidence:
        kind: documentation
  /builds/{org}:
    get:
      operationId: get_builds_org
      tags:
      - Builds
      summary: List Builds
      description: 'List builds for an organization.


        - end_ts defaults to now.

        - start_ts defaults to 28 days before end_ts.'
      x-source: https://docs.kosli.com/api-reference/builds/list-builds.md
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
        description: Number of builds per page
      - name: repo_id
        in: query
        required: false
        schema:
          type: string
        description: Filter by external VCS repo ID
      - name: repo_name
        in: query
        required: false
        schema:
          type: string
        description: Filter by repo name (e.g. 'cyber-dojo/differ')
      - name: repo_inner_id
        in: query
        required: false
        schema:
          type: string
        description: 'Filter by the repo''s internal id (the `id` in the repo response). The stable identifier: unaffected by repo renames or
          a missing external VCS id.'
      - name: start_ts
        in: query
        required: false
        schema:
          type: number
        description: Include builds created at or after this timestamp. Defaults to 28 days before end_ts
      - name: end_ts
        in: query
        required: false
        schema:
          type: number
        description: Include builds created at or before this timestamp. Defaults to now
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBuildsOrgResponse'
      x-evidence:
        kind: documentation
  /flows/{org}:
    get:
      operationId: get_flows_org
      tags:
      - Flows
      summary: List flows
      description: List flows for an organization.
      x-source: https://docs.kosli.com/api-reference/flows/list-flows.md
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: search_by_name
        in: query
        required: false
        schema:
          type: string
        description: Return flows that contain the given string in their name. Matched literally, so '-prod' finds the flows whose name ends in
          '-prod'.
      - name: case_sensitive
        in: query
        required: false
        schema:
          type: boolean
        description: Whether the search_by_name filter is case sensitive. Defaults to true.
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: The page number of response
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
        description: How many results to return per page. When omitted, all flows are returned as a plain list (no pagination envelope).
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: Sort field
      - name: sort_direction
        in: query
        required: false
        schema:
          type: string
        description: Sort direction
      - name: space_id
        in: query
        required: false
        schema:
          type: array
        description: Filter by space ID. Can be repeated for OR semantics, e.g. space_id=a&space_id=b
      - name: tag
        in: query
        required: false
        schema:
          type: array
        description: Filter by tag key or key:value. Can be repeated, e.g. tag=team or tag=team:platform
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFlowsOrgResponse'
      x-evidence:
        kind: documentation
  /flows/{org}/{flowName}:
    get:
      operationId: get_flows_org_flowName
      tags:
      - Flows
      summary: Get flow
      description: Get a flow for an organization.
      x-source: https://docs.kosli.com/api-reference/flows/get-flow.md
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: flowName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFlowsOrgFlownameResponse'
      x-evidence:
        kind: documentation
  /flows/{org}/{flowName}/rename:
    put:
      operationId: put_flows_org_flowName_rename
      tags:
      - Flows
      summary: Rename flow
      description: Rename a flow. The flow will remain available under its old name until that name is taken by another flow.
      x-source: https://docs.kosli.com/api-reference/flows/rename-flow.md
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: flowName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutFlowsOrgFlownameRenameRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutFlowsOrgFlownameRenameResponse'
      x-evidence:
        kind: documentation
  /repos/{org}:
    get:
      operationId: get_repos_org
      tags:
      - Repos
      summary: List repos
      description: 'List repos for an organization. Repos are paginated. The response includes pagination information and the list of repos. The
        list of repos is sorted by the repo name; sort_direction selects the direction (asc = A–Z, the default; desc = Z–A). Optional filters:
        name (exact match), search (case-insensitive substring match on the name), provider (VCS provider), repo_id (external repo ID), vcs_instance
        (VCS host, exact match), namespace (namespace prefix), and tag (key or key:value, repeatable). name and search are mutually exclusive;
        providing both returns a 400. repo_id is the stronger identifier as names of repos can change. So if repo_id is provided, name is ignored.
        Repos are captured when attestations include a reference to a repo. This happens automatically when using Kosli CLI v2.11.35 or higher.'
      x-source: https://docs.kosli.com/api-reference/repos/list-repos.md
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
        description: Number of repos per page
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: Filter by repo name (exact match). This is ignored if repo_id is provided. Returns empty list if no match. Mutually exclusive
          with search.
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Filter by repo name (case-insensitive substring match). Mutually exclusive with name.
      - name: provider
        in: query
        required: false
        schema:
          type: string
        description: Filter by VCS provider (e.g. github, gitlab, bitbucket, azure-devops, circleci).
      - name: repo_id
        in: query
        required: false
        schema:
          type: string
        description: Filter by external repo ID (exact match). Returns empty list if no match.
      - name: vcs_instance
        in: query
        required: false
        schema:
          type: string
        description: Filter by VCS instance/host (exact match), e.g. gitlab.company.com.
      - name: namespace
        in: query
        required: false
        schema:
          type: string
        description: Filter by namespace prefix, as a '/'-separated path, e.g. platform/backend. Matches repos nested anywhere under that path.
      - name: sort_direction
        in: query
        required: false
        schema:
          type: string
        description: 'Sort direction by repo name: asc (A–Z, default) or desc (Z–A).'
      - name: tag
        in: query
        required: false
        schema:
          type: array
        description: Filter by tag key or key:value. Can be repeated, e.g. tag=team or tag=team:security.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReposOrgResponse'
      x-evidence:
        kind: documentation
  /trails/{org}/{flowName}/{trailName}/events:
    get:
      operationId: get_trails_org_flowName_trailName_events
      tags:
      - Trails
      summary: List trail events
      x-source: https://app.kosli.com/api/v2/openapi.json
      parameters:
      - name: org
        in: path
        required: true
        schema:
          type: string
      - name: flowName
        in: path
        required: true
        schema:
          type: string
      - name: trailName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTrailsOrgFlownameTrailnameEventsResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetActionsOrgActionnumberResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the action
        type:
          type: string
          description: The type of the action
        number:
          type: integer
          description: The ID number of the action
        targets:
          type: array
          description: The targets of the action
        triggers:
          type: array
          description: The triggers of the action
        created_by:
          type: string
          description: The user who created the action
        is_created_from_slack_app:
          type: boolean
          description: Whether or not the action was created from a slack app
        is_failing:
          type: boolean
          description: Whether the action is currently failing to send notifications or not
        last_success_timestamp:
          type: number
          description: The last timestamp when the action successfully sent a notification
        last_failure_timestamp:
          type: number
          description: The last timestamp when the action failed to send notification
        created_at:
          type: number
          description: The time the action was created
        last_modified_at:
          type: number
          description: The time the action was last modified
        flows:
          type: array
          description: The flows the action is for
        environments:
          type: array
          description: The environments the action is for
    GetApiV2EnvironmentsYourorgnameResponse:
      type: object
      properties:
        schema:
          type: object
          properties:
            type:
              type: string
            items:
              type: object
              properties:
                $ref:
                  type: string
            title:
              type: string
    PostAttestationsOrgUploadsRequest:
      type: object
      properties:
        UploadPostInput:
          type: object
      required:
      - UploadPostInput
    PostAttestationsOrgUploadsResponse:
      type: object
      properties:
        '201':
          type: string
          description: Successful Response
        '400':
          type: string
          description: File size over the org's limit
        '404':
          type: string
          description: Direct uploads not available
    GetBuildsOrgResponse:
      type: object
      properties:
        '200':
          type: string
          description: Successful Response
    GetFlowsOrgResponse:
      type: object
      properties:
        data:
          type: array
          description: List of flows
        pagination:
          type: object
          description: Pagination info (only present when there are multiple pages)
    GetFlowsOrgFlownameResponse:
      type: object
      properties:
        '200':
          type: string
          description: Successful Response
        '404':
          type: string
          description: Flow not found
    PutFlowsOrgFlownameRenameRequest:
      type: object
      properties:
        new_name:
          type: string
          description: New Name
      required:
      - new_name
    PutFlowsOrgFlownameRenameResponse:
      type: object
      properties:
        '200':
          type: string
          description: Successful flow rename
        '404':
          type: object
          description: Flow not found
    GetReposOrgResponse:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total_pages:
          type: integer
        total_count:
          type: integer
        repos:
          type: array
    GetTrailsOrgFlownameTrailnameEventsResponse:
      type: object
      properties:
        '200':
          type: string
          description: Successful Response
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Actions
- name: Api
- name: Attestations
- name: Builds
- name: Flows
- name: Repos
- name: Trails