openapi: 3.2.0
info:
  title: Latitude Projects API
  version: v1
  description: Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked.
  servers:
  - url: https://api.latitude.so
    description: Production
servers:
- url: https://api.latitude.so
tags:
- name: Projects
paths:
  /v1/projects:
    post:
      tags:
      - Projects
      x-fern-sdk-group-name: projects
      x-fern-sdk-method-name: create
      summary: Create project
      description: Creates a new project within the organization. The name must be unique within the org.
      security:
      - ApiKeyAuth: []
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectBody'
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
      - Projects
      x-fern-sdk-group-name: projects
      x-fern-sdk-method-name: list
      summary: List projects
      description: Returns every project in the organization. The response uses the standard paginated shape; the project list currently fits in a single page (`nextCursor` is always `null`).
      security:
      - ApiKeyAuth: []
      operationId: listProjects
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProjects'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{projectSlug}:
    get:
      tags:
      - Projects
      x-fern-sdk-group-name: projects
      x-fern-sdk-method-name: get
      summary: Get project
      description: Returns a single project by slug.
      security:
      - ApiKeyAuth: []
      operationId: getProject
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      responses:
        '200':
          description: Project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Projects
      x-fern-sdk-group-name: projects
      x-fern-sdk-method-name: update
      summary: Update project
      description: Updates a project's name and/or settings. Renaming never changes the slug, and the slug cannot be changed via the API (only from the dashboard). Use `id` or `slug` as stable references.
      security:
      - ApiKeyAuth: []
      operationId: updateProject
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectBody'
      responses:
        '200':
          description: Updated project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Projects
      x-fern-sdk-group-name: projects
      x-fern-sdk-method-name: delete
      summary: Delete project
      description: Deletes a project by slug.
      security:
      - ApiKeyAuth: []
      operationId: deleteProject
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      responses:
        '204':
          description: Project deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{projectSlug}/usage:
    get:
      tags:
      - Projects
      x-fern-sdk-group-name: projects
      x-fern-sdk-method-name: usage
      summary: Get project usage
      description: Returns the credits one project spent in the current billing period, broken down by product area.
      security:
      - ApiKeyAuth: []
      operationId: getProjectUsage
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      responses:
        '200':
          description: Current period usage for the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectUsageResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NotificationsSetting:
      type: object
      properties:
        incidents:
          $ref: '#/components/schemas/IncidentNotificationsSetting'
        destinations:
          $ref: '#/components/schemas/DestinationNotificationsSetting'
      description: Per-group project-level notification toggles (`incidents`, `destinations`).
    ProjectSettings:
      type: object
      nullable: true
      properties:
        keepMonitoring:
          type: boolean
          description: When `true`, the evaluation linked to an signal keeps running after the signal is resolved. When `false`, resolving the signal stops the evaluation. Defaults to `true` when omitted.
        redaction:
          $ref: '#/components/schemas/RedactionSetting'
        notifications:
          $ref: '#/components/schemas/NotificationsSetting'
        escalation:
          $ref: '#/components/schemas/EscalationSetting'
      description: Per-project settings overrides. `null` means inherit from the organization.
    ProjectUsageResponse:
      allOf:
      - $ref: '#/components/schemas/UsageProject'
      - type: object
        properties:
          period:
            type: object
            properties:
              start:
                type: string
                description: ISO-8601 start of the current billing period.
              end:
                type: string
                description: ISO-8601 end of the current billing period, exclusive.
            required:
            - start
            - end
            description: Billing period the usage figures cover.
        required:
        - period
    DestinationNotificationsSetting:
      type: object
      properties:
        quarantine:
          type: boolean
          description: Notify org members when a data destination is quarantined after repeated sync failures. Defaults to `true` when omitted.
      description: Project-level opt-out for data-destination notifications.
    PaginatedProjects:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Project'
          description: Page of items, in the requested sort order.
        nextCursor:
          type: string
          nullable: true
          description: Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue.
        hasMore:
          type: boolean
          description: '`true` when there is at least one more page after this one.'
      required:
      - items
      - nextCursor
      - hasMore
    IncidentNotificationsSetting:
      type: object
      properties:
        signal.escalating:
          type: boolean
          description: Send a notification when an active signal is escalating in volume or severity. Defaults to `true` when omitted.
        monitor.match:
          type: boolean
          description: Send a notification when a match monitor opens an incident. Defaults to `true` when omitted.
        monitor.threshold:
          type: boolean
          description: Send a notification when a threshold monitor opens an incident. Defaults to `true` when omitted.
        monitor.escalating:
          type: boolean
          description: Send a notification when an escalating monitor opens an incident. Defaults to `true` when omitted.
      description: Per-alert-kind opt-out for incident notifications.
    UpdateProjectBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: New human-readable name. Renaming never changes the slug.
        settings:
          $ref: '#/components/schemas/ProjectSettingsPatch'
        flaggers:
          type: object
          properties:
            frustration:
              type: boolean
            nsfw:
              type: boolean
            refusal:
              type: boolean
            laziness:
              type: boolean
            jailbreaking:
              type: boolean
            forgetting:
              type: boolean
            trashing:
              type: boolean
            bluffing:
              type: boolean
            pii-leakage:
              type: boolean
            incompletion:
              type: boolean
            tool-call-errors:
              type: boolean
            output-schema-validation:
              type: boolean
            empty-response:
              type: boolean
            low-cache-hit-rate:
              type: boolean
            task-failure:
              type: boolean
          description: Enable or disable specific flaggers for the project. Keys are flagger slugs; values are the new `enabled` state. Omitted slugs are left untouched.
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    RedactionSetting:
      type: object
      properties:
        mode:
          type: string
          enum:
          - 'off'
          - enforce
          description: '`enforce` scans span content as it is ingested and replaces matches with a labelled placeholder such as `[REDACTED_EMAIL]`; `off` scans nothing. Defaults to `off` when omitted. Applies only to spans ingested after the change, takes effect within a minute, and redacted content cannot be recovered.'
        entities:
          type: array
          items:
            type: string
            enum:
            - email
            - phone
            - credit_card
            - iban
            - us_ssn
            - ip_address
            - secret
          maxItems: 7
          description: 'Which categories to look for. Defaults to email, phone, credit_card, iban, us_ssn, secret when omitted; `ip_address` is off by default because a dotted quad and a four-part version string are the same string. Detection is pattern based: it reliably catches structured identifiers, and does not catch names, addresses, or free-form personal detail.'
        scopes:
          type: object
          properties:
            metadata:
              type: boolean
              description: Also scan the metadata map and tags. Defaults to `false` when omitted, because metadata is usually operational and redacting it removes values you filter and group by.
          description: Which span fields to scan beyond message and tool content.
        identities:
          type: string
          enum:
          - keep
          - pseudonymize
          description: How to handle `userId` and `userEmail`. `keep` stores them unchanged; `pseudonymize` replaces each with a stable per-organization pseudonym so filtering and grouping by user keep working. Defaults to `keep` when omitted. Deployments with no pseudonym secret configured remove the identifier entirely instead.
      description: Server-side PII redaction applied before spans are stored. An organization-wide policy can override this one; when the organization locks its policy, project values are ignored entirely rather than merged.
    UsageProject:
      type: object
      properties:
        id:
          type: string
          description: Stable project identifier.
        slug:
          type: string
          nullable: true
          description: Project slug. `null` when the project no longer exists.
        name:
          type: string
          nullable: true
          description: Project name. `null` when the project no longer exists.
        credits:
          type: integer
          description: Credits the project spent during the period.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/UsageCategory'
          description: The project's credits by product area, largest first.
      required:
      - id
      - slug
      - name
      - credits
      - categories
    UsageCategory:
      type: object
      properties:
        category:
          type: string
          enum:
          - traces
          - flaggers
          - signals
          - behaviors
          - annotations
          - other
          description: Product area the credits were spent on.
        credits:
          type: integer
          description: Credits spent in this category during the period.
      required:
      - category
      - credits
    Project:
      type: object
      properties:
        id:
          type: string
          description: Stable project identifier (CUID2).
        organizationId:
          type: string
          description: Organization that owns this project.
        name:
          type: string
          description: Human-readable name.
        slug:
          type: string
          description: URL-safe slug. Set from `name` at creation; renaming never changes it. It can only be changed from the dashboard, not via the API.
        settings:
          $ref: '#/components/schemas/ProjectSettings'
        firstTraceAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp of the first ingested trace. `null` until the first trace lands.
        deletedAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp at which the project was deleted. `null` while the project is active.
        lastEditedAt:
          type: string
          description: ISO-8601 timestamp of the most recent name/settings edit.
        createdAt:
          type: string
          description: ISO-8601 timestamp of creation.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of the last metadata change.
      required:
      - id
      - organizationId
      - name
      - slug
      - settings
      - firstTraceAt
      - deletedAt
      - lastEditedAt
      - createdAt
      - updatedAt
    CreateProjectBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Human-readable name for the project. Must be unique within the organization.
      required:
      - name
    ProjectSettingsPatch:
      type: object
      properties:
        keepMonitoring:
          type: boolean
          description: When `true`, the evaluation linked to an signal keeps running after the signal is resolved. When `false`, resolving the signal stops the evaluation. Defaults to `true` when omitted.
        redaction:
          $ref: '#/components/schemas/RedactionSetting'
        notifications:
          $ref: '#/components/schemas/NotificationsSetting'
        escalation:
          $ref: '#/components/schemas/EscalationSetting'
      description: Patch the project's settings overrides. Only the fields you send are changed; omitted fields keep their stored values. To clear overrides entirely, edit via the web UI.
    EscalationSetting:
      type: object
      properties:
        sensitivity:
          type: integer
          minimum: 1
          maximum: 6
          description: Sensitivity of the escalation detector, 1 (most sensitive, more incidents) to 6 (least sensitive, fewer incidents). Defaults to a balanced value when omitted.
      description: Tuning parameters for the escalation detector. Affects detector behaviour regardless of whether notifications are enabled.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Organization-scoped API key, sent as `Authorization: Bearer <key>`.'
      x-fern-bearer:
        name: apiKey
        env: LATITUDE_API_KEY