openapi: 3.2.0
info:
  contact:
    email: support@sprig.com
    name: Support
  description: Sprig is a continuous product research tool that helps you automatically capture the user insights you need to consistently improve your product, user experience, marketing, and more.
  title: Sprig Users API
  version: 2.2.1
servers:
- url: https://api.sprig.com
tags:
- name: Users
paths:
  /v2/users:
    parameters: []
    post:
      description: 'Endpoint facilitating the programatic upsertion of a user.

        Users must be upserted 1 at a time.

        Events created for this user are for historical tracking purposes. Any event tied to a user through this endpoint will not trigger a study through Sprig''s SDK.

        Attributes and attribute values can be created and tied to a user through this endpoint.'
      operationId: post-user-v2
      parameters:
      - $ref: '#/components/parameters/Authorization-API-Key'
      requestBody:
        content:
          application/json:
            examples:
              example user:
                value:
                  attributes:
                    customer: 'true'
                  email: user@test.com
                  events:
                  - event: login
                    timestamp: 1626448859836
                  userId: '12347'
            schema:
              properties:
                attributes:
                  description: Key value pairs of attributes
                  properties:
                    attributeName:
                      description: Attribute name and value. Attributes limited to total of 100 values
                      type: string
                  type: object
                emailAddress:
                  description: Valid Email to track visitor by
                  type: string
                events:
                  items:
                    properties:
                      event:
                        description: Name of event already being tracked in Sprig
                        type: string
                      timestamp:
                        description: Unix timestamp in milliseconds
                        type: integer
                    type: object
                  type: array
                userId:
                  description: Existing or desired id for visitor
                  type: string
              required:
              - userId
              type: object
        description: Post the necessary fields for the API to upsert a new user.
      responses:
        '202':
          $ref: '#/components/responses/202'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
      summary: Upsert a User
      tags:
      - Users
  /v2/users/{userId}:
    parameters:
    - description: Id of an existing user.
      in: path
      name: userId
      required: true
      schema:
        type: string
    get:
      description: 'Endpoint that allows the retrieval of a visitor based on a known User ID.

        This endpoint can only recover visitors with user IDs, so please ensure your Sprig implementation has user tracking configured correctly based on your SDK installation: /docs/Installation/introduction-web/index

        This endpoint will retrieve visitor info, a list of attributes tied to the visitor, and a list of events with relevant filter criteria.'
      operationId: get-v2-users-:userId
      parameters:
      - $ref: '#/components/parameters/Authorization-API-Key'
      responses:
        '200':
          content:
            application/json:
              examples: {}
              schema:
                $ref: '#/components/schemas/Userv2'
          description: OK
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Retrieve a User
      tags:
      - Users
components:
  responses:
    '500':
      description: Something went wrong on Sprig's side. These are very rare :)
    '400':
      content:
        application/json:
          schema:
            properties:
              error:
                type: string
      description: Bad Request
    '202':
      description: Accepted
    '404':
      description: Not Found
    '422':
      description: Unprocessable Entity
  parameters:
    Authorization-API-Key:
      description: API-Key YOUR_API_KEY
      in: header
      name: Authorization
      required: true
      schema:
        type: string
  schemas:
    Userv2:
      description: API V2 user model
      properties:
        attributes:
          type: object
        createdAt:
          type: number
        events:
          items:
            properties:
              count:
                type: number
              createdAt:
                type: number
              event:
                minLength: 1
                type: string
              updatedAt:
                type: number
            type: object
          minItems: 1
          type: array
          uniqueItems: true
        externalUserId:
          minLength: 1
          nullable: true
          type: string
        id:
          minLength: 1
          type: string
      title: ''
      type: object
      x-examples:
        V2 User:
          attributes:
            completed_flow: false
            plan: enterprise
          createdAt: 1612739790947
          events:
          - count: 1
            createdAt: 1612739790947
            event: Clicked Signup
            updatedAt: 1612739912314
          id: a926111b-fa62-49f7-8666-2c94ca8b18fc
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Use `API-Key YOUR_API_KEY` for v2 endpoints or `Bearer YOUR_API_KEY` for export endpoints.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true