openapi: 3.1.0
info:
  title: Nudge Security API
  description: >-
    The Nudge Security REST API enables programmatic access to retrieve data
    about apps, accounts, OAuth grants, security events, fields, users, user
    groups, labels, notifications, findings, playbooks, app-to-app
    integrations, app instances, AI sessions and prompts, and the browser
    extension. It supports integration with SIEM, SOAR, and ticketing systems
    and allows management of custom fields and classifications. The API is
    rate limited to 1200 requests per 5-minute period. API tokens auto-expire
    after 4 weeks of no use.
  version: '1.0'
  contact:
    name: Nudge Security
    url: https://help.nudgesecurity.com/
externalDocs:
  description: Nudge Security API Reference
  url: https://nudgesecurity.readme.io/reference
servers:
  - url: https://api.nudgesecurity.io/api/1.0
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Apps
    description: Search, retrieve, and manage discovered SaaS applications.
  - name: Accounts
    description: Search and retrieve user accounts associated with apps.
  - name: OAuth Grants
    description: Search and retrieve OAuth grants issued to applications.
  - name: Events
    description: Search and retrieve security events generated by Nudge Security.
  - name: Users
    description: Search and retrieve user records.
  - name: User Groups
    description: Search and retrieve user groups and their members.
  - name: Notifications
    description: Search and retrieve configured notification events.
  - name: Fields
    description: Manage custom fields and their allowed values.
  - name: Labels
    description: Manage labels used to classify apps and accounts.
  - name: Findings
    description: Search and retrieve security findings.
  - name: App Integrations
    description: Search and retrieve app-to-app integrations.
paths:
  /apps:
    get:
      tags: [Apps]
      summary: Search apps
      description: Search and list SaaS applications discovered by Nudge Security.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: A paginated list of apps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppList'
        '401': { $ref: '#/components/responses/Unauthorized' }
  /apps/{app_id}:
    get:
      tags: [Apps]
      summary: Get app
      description: Retrieve a single SaaS application by ID.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The requested app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '404': { $ref: '#/components/responses/NotFound' }
  /apps/app-category/{app_id}:
    post:
      tags: [Apps]
      summary: Set app category
      description: Assign the app to a service category.
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [category]
              properties:
                category:
                  type: string
                  description: Service category such as Finance, HR, Marketing, Sales, Analytics, Security.
      responses:
        '200': { description: Success }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /accounts:
    get:
      tags: [Accounts]
      summary: Search accounts
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: A paginated list of accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /accounts/{account_id}:
    get:
      tags: [Accounts]
      summary: Get account
      parameters:
        - name: account_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The requested account.
          content:
            application/json:
              schema: { type: object }
  /oauth-grants:
    get:
      tags: [OAuth Grants]
      summary: Search OAuth grants
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: A paginated list of OAuth grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /oauth-grants/{grant_id}:
    get:
      tags: [OAuth Grants]
      summary: Get OAuth grant
      parameters:
        - name: grant_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The requested OAuth grant.
          content:
            application/json:
              schema: { type: object }
  /events:
    get:
      tags: [Events]
      summary: Search events
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: A paginated list of events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /events/{event_id}:
    get:
      tags: [Events]
      summary: Get event
      parameters:
        - name: event_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema: { type: object }
  /users:
    get:
      tags: [Users]
      summary: Search users
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: A paginated list of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /user-groups:
    get:
      tags: [User Groups]
      summary: Search user groups
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: A paginated list of user groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /user-groups/{group_id}/members:
    get:
      tags: [User Groups]
      summary: List user group members
      parameters:
        - name: group_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Members of the group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /notifications:
    get:
      tags: [Notifications]
      summary: Search notifications
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of notifications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /fields:
    get:
      tags: [Fields]
      summary: Search fields
      responses:
        '200':
          description: A list of custom fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
    post:
      tags: [Fields]
      summary: Create field
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, type]
              properties:
                name: { type: string }
                type: { type: string }
                allowed_values:
                  type: array
                  items: { type: string }
      responses:
        '201':
          description: The created field.
          content:
            application/json:
              schema: { type: object }
  /labels:
    get:
      tags: [Labels]
      summary: Search labels
      responses:
        '200':
          description: A list of labels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
    post:
      tags: [Labels]
      summary: Create label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                color: { type: string }
      responses:
        '201':
          description: The created label.
          content:
            application/json:
              schema: { type: object }
  /findings:
    get:
      tags: [Findings]
      summary: Search findings
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of findings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
  /app-to-app-integrations:
    get:
      tags: [App Integrations]
      summary: Search app-to-app integrations
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of app-to-app integrations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
  parameters:
    AppId:
      name: app_id
      in: path
      required: true
      schema:
        type: integer
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Search:
      name: search
      in: query
      required: false
      schema:
        type: string
  responses:
    BadRequest:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error: { type: string }
        message: { type: string }
    App:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        category: { type: string }
        domain: { type: string }
        status: { type: string }
        first_seen: { type: string, format: date-time }
        last_seen: { type: string, format: date-time }
    AppList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/App'
        page: { type: integer }
        per_page: { type: integer }
        total: { type: integer }
    PaginatedList:
      type: object
      properties:
        data:
          type: array
          items: { type: object }
        page: { type: integer }
        per_page: { type: integer }
        total: { type: integer }