{
  "openapi": "3.0.0",
  "info": {
    "title": "Userpilot API",
    "version": "1.0.0",
    "termsOfService": "https://userpilot.io/terms-of-service/",
    "description": "Userpilot's API suite for user identification, event tracking, data import/export, and user/company management.\n\nAuthentication:\n All endpoints that require authentication expect an HTTP header in the following format:\n\n Authorization: Token {{API_KEY}}\n\nExample (cURL):\n curl -X GET 'https://appex.userpilot.io/v1/identify' \\\n   -H 'Authorization: Token abcd1234efgh5678' \\\n   -H 'Content-Type: application/json'\n\nContact Support:\n Email: support@userpilot.com",
    "contact": {
      "name": "Userpilot",
      "url": "https://userpilot.io",
      "email": "support@userpilot.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://appex.userpilot.io",
      "description": "Application endpoint"
    }
  ],
  "paths": {
    "/api/v1/analytics/exports/jobs/{job_id}": {
      "parameters": [
        {
          "name": "job_id",
          "in": "path",
          "required": true,
          "description": "(Required) Unique identifier for the export job",
          "example": "<uuid>",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Show Job by Job ID",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "OK - Export job details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "app_token": {
                      "type": "string"
                    },
                    "completed_chunks": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "current_chunk": {
                      "type": "string"
                    },
                    "end_time": {
                      "type": "string"
                    },
                    "job_id": {
                      "type": "string"
                    },
                    "presigned_urls": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "filename": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "progress": {
                      "type": "string"
                    },
                    "start_time": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "all_chunks": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "type": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "Unauthorized - Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "details": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          },
                          "error_code": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "Not Found - Export job not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "details": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          },
                          "error_code": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/jobs/": {
      "parameters": [],
      "get": {
        "summary": "Show Jobs",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "OK - List of export jobs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "elapsed_time": {
                        "type": "string"
                      },
                      "elapsed_time_seconds": {
                        "type": "string"
                      },
                      "end_time": {
                        "type": "string"
                      },
                      "job_id": {
                        "type": "string"
                      },
                      "progress": {
                        "type": "string"
                      },
                      "start_time": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "Unauthorized - Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "details": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          },
                          "error_code": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/user_properties": {
      "get": {
        "summary": "Get user properties",
        "description": "Retrieve a list of user properties available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of user properties.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 1,
                    "type": "user_property",
                    "key": "email",
                    "display_name": "Email",
                    "data_type": "string",
                    "is_auto_property": false
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/company_properties": {
      "get": {
        "summary": "Get company properties",
        "description": "Retrieve a list of company properties available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of company properties.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 10,
                    "type": "company_property",
                    "key": "company_name",
                    "display_name": "Company Name",
                    "data_type": "string",
                    "is_auto_property": false
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/segments": {
      "get": {
        "summary": "Get segments",
        "description": "Retrieve a paginated list of segments available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of segments.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "cursor": {
                          "type": "object",
                          "properties": {
                            "after": {
                              "type": "string",
                              "nullable": true
                            },
                            "before": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": 101,
                      "title": "Active Users",
                      "usage": "all",
                      "category": "user_id",
                      "is_hidden": false,
                      "is_protected": false,
                      "status": "published"
                    }
                  ],
                  "metadata": {
                    "cursor": {
                      "after": "...",
                      "before": null
                    },
                    "limit": 50,
                    "total_count": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/features_events": {
      "get": {
        "summary": "Get features & events",
        "description": "Retrieve a list of features and events available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of features and events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "display_name": "Feature A",
                    "key": "feature_a",
                    "data_type": "string"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/events_properties": {
      "get": {
        "summary": "Get trackable events' properties/attributes (paginated)",
        "description": "Retrieve a paginated list of trackable event properties and attributes. Supports cursor-based pagination.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          },
          {
            "name": "after_cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Cursor for pagination. Use the value from the previous response's metadata.cursor.after."
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of event properties.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "cursor": {
                          "type": "object",
                          "properties": {
                            "after": {
                              "type": "string",
                              "nullable": true
                            },
                            "before": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": 12,
                      "key": "url",
                      "display_name": "URL",
                      "is_auto_property": true,
                      "is_mobile_auto_property": false,
                      "data_type": "string",
                      "category": "css_attribute",
                      "description": "Page URL",
                      "is_archived": false,
                      "event": {
                        "id": 33,
                        "display_name": "page_view"
                      },
                      "inserted_at": "2025-01-01T00:00:00Z",
                      "last_seen": "2025-01-10T00:00:00Z"
                    }
                  ],
                  "metadata": {
                    "cursor": {
                      "after": "...",
                      "before": null
                    },
                    "limit": 50,
                    "total_count": 53
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/flows": {
      "get": {
        "summary": "Get flows (experiences)",
        "description": "Retrieve a list of flows (experiences) available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of flows (experiences).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 123,
                    "title": "Onboarding Flow"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/banners": {
      "get": {
        "summary": "Get banners",
        "description": "Retrieve a list of banners available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of banners.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 77,
                    "title": "Promo Banner"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/embeds": {
      "get": {
        "summary": "Get embeds",
        "description": "Retrieve a list of embeds (banners and cards) available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of embeds (banners and cards).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 77,
                    "title": "Promo Banner",
                    "type": "banner"
                  },
                  {
                    "id": 92,
                    "title": "Feature Card",
                    "type": "card"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/spotlights": {
      "get": {
        "summary": "Get spotlights",
        "description": "Retrieve a list of spotlights available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of spotlights.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 88,
                    "title": "New Feature Spotlight"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/surveys": {
      "get": {
        "summary": "Get surveys (with modules)",
        "description": "Retrieve a list of surveys (with modules) available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of surveys (with modules).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "id": 45,
                    "title": "CSAT Survey",
                    "platform": "web",
                    "modules": [
                      {
                        "id": 1,
                        "order": 1,
                        "type": "open_text",
                        "question": "How was it?"
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/resource_center_modules": {
      "get": {
        "summary": "Get resource center modules",
        "description": "Retrieve a list of resource center modules available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of resource center modules.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "display_name": "Resource Center Module A",
                    "key": "resource_center_module_a",
                    "data_type": "string"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports/lookups/checklists": {
      "get": {
        "summary": "Get checklists (with tasks)",
        "description": "Retrieve a list of checklists (with tasks) available for export.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthorizationHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of checklists (with tasks).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "example": [
                  {
                    "display_name": "Checklist A",
                    "key": "checklist_a",
                    "data_type": "string"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analytics/exports": {
      "parameters": [
        {
          "$ref": "#/components/parameters/AuthorizationHeader"
        }
      ],
      "post": {
        "summary": "Trigger an Export Job",
        "parameters": [
          {
            "name": "Content-Type",
            "description": "The content type of the request body. Must be `application/json`.",
            "in": "header",
            "required": false,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Accept",
            "description": "The content type of the response body. Must be `application/json`.",
            "in": "header",
            "required": false,
            "example": "application/json",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "Created - Export job successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "environment_app_token": {
                      "type": "string",
                      "description": "The app token of the environment.",
                      "example": "NX-RE213S2"
                    },
                    "environment_name": {
                      "type": "string",
                      "description": "The name of the environment.",
                      "example": "production"
                    },
                    "job_id": {
                      "type": "string",
                      "description": "The ID of the export job.",
                      "example": "123e4567-e89b-12d3-a456-426614174000"
                    },
                    "links": {
                      "type": "string",
                      "description": "The links to the export job."
                    },
                    "start_time": {
                      "type": "string",
                      "description": "The start time of the export job."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "Unauthorized - Invalid API key or insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "details": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          },
                          "error_code": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "example": "application/json"
              }
            },
            "description": "Conflict - Export job already in progress",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "details": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          },
                          "error_code": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  },
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "event_type": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "user_id": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "company_id": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "segment_id": {
                    "type": "string"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "avro",
                      "csv",
                      "ndjson",
                      "parquet"
                    ]
                  },
                  "exclusions": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "AuthorizationHeader": {
        "name": "Authorization",
        "in": "header",
        "required": true,
        "description": "API authentication token in the format: `Token {{API_KEY}}`. Obtain your API key from the [Userpilot Environment Settings](https://run.userpilot.io/environment).",
        "schema": {
          "type": "string"
        },
        "example": "Token abcd1234efgh5678"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "details": {
                  "type": "string",
                  "description": "Detailed error information."
                },
                "error": {
                  "type": "string",
                  "description": "Short error code or label."
                },
                "error_code": {
                  "type": "string",
                  "description": "Error code for programmatic handling."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable error message."
                }
              }
            }
          }
        },
        "description": "Standard error response object."
      }
    }
  }
}