openapi: 3.1.0
info:
  title: Sentry Alerts Organizations API
  description: The Alerts API provides endpoints for managing alert rules in Sentry, including creating, retrieving, updating, and deleting metric alert rules and issue alert rules, as well as managing spike protection notification actions.
  version: 0.0.1
  contact:
    name: Sentry Support
    url: https://sentry.io/support/
    email: support@sentry.io
servers:
- url: https://sentry.io/api/0
  description: Sentry Production API
security:
- BearerAuth: []
tags:
- name: Organizations
  description: Manage Sentry organizations
paths:
  /organizations/:
    get:
      operationId: listOrganizations
      summary: Sentry List organizations
      description: Returns a list of organizations available to the authenticated session. This is particularly useful for tokens with access to multiple organizations.
      tags:
      - Organizations
      parameters:
      - name: cursor
        in: query
        description: A pointer to the last object fetched and its sort order for pagination.
        schema:
          type: string
      responses:
        '200':
          description: A list of organizations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
  /organizations/{organization_id_or_slug}/:
    get:
      operationId: retrieveOrganization
      summary: Sentry Retrieve an organization
      description: Returns details for a specific organization identified by slug.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      responses:
        '200':
          description: Organization details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Organization not found.
    put:
      operationId: updateOrganization
      summary: Sentry Update an organization
      description: Updates various attributes and configurable settings for the given organization.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The human-readable name of the organization.
                slug:
                  type: string
                  description: The unique URL slug for this organization.
      responses:
        '200':
          description: Organization updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Organization not found.
  /organizations/{organization_id_or_slug}/projects/:
    get:
      operationId: listOrganizationProjects
      summary: Sentry List organization projects
      description: Returns a list of projects bound to the organization.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      - name: cursor
        in: query
        description: Pagination cursor.
        schema:
          type: string
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
  /organizations/{organization_id_or_slug}/shortids/{short_id}/:
    get:
      operationId: resolveShortId
      summary: Sentry Resolve a short ID
      description: Resolves a short ID to the project slug and internal issue ID, useful for URL construction.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      - name: short_id
        in: path
        required: true
        description: The short ID to resolve (e.g., PROJECT-123).
        schema:
          type: string
      responses:
        '200':
          description: Resolved short ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationSlug:
                    type: string
                  projectSlug:
                    type: string
                  shortId:
                    type: string
                  group:
                    type: object
                    properties:
                      id:
                        type: string
                      title:
                        type: string
        '401':
          description: Unauthorized.
        '404':
          description: Short ID not found.
  /organizations/{organization_id_or_slug}/eventids/{event_id}/:
    get:
      operationId: resolveEventId
      summary: Sentry Resolve an event ID
      description: Resolves an event ID to the event's project and issue.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      - name: event_id
        in: path
        required: true
        description: The event ID to resolve.
        schema:
          type: string
      responses:
        '200':
          description: Resolved event ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationSlug:
                    type: string
                  projectSlug:
                    type: string
                  groupId:
                    type: string
                  eventId:
                    type: string
                  event:
                    type: object
        '401':
          description: Unauthorized.
        '404':
          description: Event not found.
  /organizations/{organization_id_or_slug}/stats_v2/:
    get:
      operationId: retrieveEventCounts
      summary: Sentry Retrieve event counts (v2)
      description: Returns event counts for the organization, optionally grouped by project.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      - name: field
        in: query
        required: true
        description: The field to query (e.g., sum(quantity), sum(times_seen)).
        schema:
          type: string
      - name: statsPeriod
        in: query
        description: Stats period (e.g., 24h, 14d).
        schema:
          type: string
      - name: groupBy
        in: query
        description: Group results by category, outcome, or project.
        schema:
          type: string
      responses:
        '200':
          description: Event count statistics.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
  /organizations/{organization_id_or_slug}/relay_usage/:
    get:
      operationId: listOrganizationTrustedRelays
      summary: Sentry List organization trusted relays
      description: Returns a list of trusted relays for the organization.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      responses:
        '200':
          description: A list of trusted relays.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    publicKey:
                      type: string
                    name:
                      type: string
                    description:
                      type: string
                    created:
                      type: string
                      format: date-time
                    lastModified:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
  /organizations/{organization_id_or_slug}/client-keys/:
    get:
      operationId: listOrganizationClientKeys
      summary: Sentry List organization client keys
      description: Returns a list of client keys bound to the organization.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdOrSlug'
      - name: cursor
        in: query
        description: Pagination cursor.
        schema:
          type: string
      responses:
        '200':
          description: A list of client keys.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    label:
                      type: string
                    public:
                      type: string
                    secret:
                      type: string
                    projectId:
                      type: integer
                    isActive:
                      type: boolean
                    dateCreated:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
components:
  parameters:
    OrganizationIdOrSlug:
      name: organization_id_or_slug
      in: path
      required: true
      description: The ID or slug of the organization.
      schema:
        type: string
  schemas:
    Project:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        platform:
          type: string
          nullable: true
        dateCreated:
          type: string
          format: date-time
        isBookmarked:
          type: boolean
        isMember:
          type: boolean
        hasAccess:
          type: boolean
      required:
      - id
      - slug
      - name
    Organization:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the organization.
        slug:
          type: string
          description: The URL-friendly slug of the organization.
        name:
          type: string
          description: The human-readable name of the organization.
        dateCreated:
          type: string
          format: date-time
          description: When the organization was created.
        status:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        isEarlyAdopter:
          type: boolean
          description: Whether the organization is an early adopter.
        avatar:
          type: object
          properties:
            avatarType:
              type: string
            avatarUuid:
              type: string
              nullable: true
      required:
      - id
      - slug
      - name
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authentication token for the Sentry API.