openapi: 3.1.0 info: title: Aha! Account backups Historical Audits API version: 1.0.0 description: Complete API documentation for Aha! generated from actual test responses contact: name: Aha! Support url: https://www.aha.io/support servers: - url: https://{account-domain}.aha.io/api/v1 description: Aha! API Server variables: account-domain: description: Your Aha! account domain default: company security: - OAuth2: [] - ApiKeyAuth: [] - CookieAuth: [] tags: - name: Historical Audits paths: /api/v1/historical_audits: get: summary: Read the contents of the historical index description: "The historical audits endpoint is similar to the the Audits endpoint, but searches for audit records generated more than 12 calendar months ago. For searches of more recent data, the much more performant [Audits API](/api/resources/audits) should be used.\n\nThe [historical index](/api/resources/historical_audits/read_the_contents_of_the_historical_index) should first be used to identify time-periods of interest, and then a search can be conducted to fetch the full details of the audit records from that period.\n\nThere are three important caveats to using this API:\n\n1. Searching through historical audits is an asynchronous operation. A search must first be [created](/api/resources/historical_audits/create_an_audit_search), and then the data may be [consumed later](/api/resources/historical_audits/read_the_results_of_an_audit_search)\n2. Searching through historical audits imposes a stricter rate-limit than the general rate limit of the API. This API also enforces rate-limiting through a _token-based system._\n 1. Each Audits search consumes a specific number of tokens. The token cost of a search will be presented to the user through the [read results operation.](/api/resources/historical_audits/read_the_results_of_an_audit_search)\n 2. The token cost of a request is only known after the search completes, and corresponds to the amount of data which was required to be scanned to fulfill the request. Specifying additional filters, such as `user_id`, `auditable_type`, and `audit_action` will decrease the token cost.\n 3. Upon making a request, the maximum token cost for a query will be charged to your account. The difference between the actual token cost and the maximum token cost will be refunded when the search completes and you read the search data.\n 4. Tokens are continually replenished. You can see the current number of tokens available in the `X-Historical-Tokens-Available` header, present on every response to these resources.\n 5. Reading from the [historical index](/api/resources/historical_audits/read_the_contents_of_the_historical_index) does not consume any tokens.\n3. Only administrators are able to perform historical audit searches." tags: - Historical Audits parameters: - name: created_since in: query required: false schema: type: string example: '2019-01-01T00:00:00Z' - name: created_before in: query required: false schema: type: string example: '2019-01-01T00:00:00Z' - name: auditable_type in: query required: false schema: type: string example: Feature - name: user_id in: query required: false schema: type: string example: '1049303076' responses: '200': description: Successful operation headers: Content-Type: description: application/json; charset=utf-8 schema: type: string content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/HistoricalAuditsGetResponse' example: historical_audits: - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' pagination: total_records: 3 total_pages: 1 current_page: 1 security: - OAuth2: [] - ApiKeyAuth: [] - CookieAuth: [] post: summary: Create an audit search description: "The historical audits endpoint is similar to the the Audits endpoint, but searches for audit records generated more than 12 calendar months ago. For searches of more recent data, the much more performant [Audits API](/api/resources/audits) should be used.\n\nThe [historical index](/api/resources/historical_audits/read_the_contents_of_the_historical_index) should first be used to identify time-periods of interest, and then a search can be conducted to fetch the full details of the audit records from that period.\n\nThere are three important caveats to using this API:\n\n1. Searching through historical audits is an asynchronous operation. A search must first be [created](/api/resources/historical_audits/create_an_audit_search), and then the data may be [consumed later](/api/resources/historical_audits/read_the_results_of_an_audit_search)\n2. Searching through historical audits imposes a stricter rate-limit than the general rate limit of the API. This API also enforces rate-limiting through a _token-based system._\n 1. Each Audits search consumes a specific number of tokens. The token cost of a search will be presented to the user through the [read results operation.](/api/resources/historical_audits/read_the_results_of_an_audit_search)\n 2. The token cost of a request is only known after the search completes, and corresponds to the amount of data which was required to be scanned to fulfill the request. Specifying additional filters, such as `user_id`, `auditable_type`, and `audit_action` will decrease the token cost.\n 3. Upon making a request, the maximum token cost for a query will be charged to your account. The difference between the actual token cost and the maximum token cost will be refunded when the search completes and you read the search data.\n 4. Tokens are continually replenished. You can see the current number of tokens available in the `X-Historical-Tokens-Available` header, present on every response to these resources.\n 5. Reading from the [historical index](/api/resources/historical_audits/read_the_contents_of_the_historical_index) does not consume any tokens.\n3. Only administrators are able to perform historical audit searches." tags: - Historical Audits parameters: [] responses: '200': description: Successful operation headers: Content-Type: description: application/json; charset=utf-8 schema: type: string content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/HistoricalAuditsPostResponse' example: search_id: '6776881149486782892' security: - OAuth2: [] - ApiKeyAuth: [] - CookieAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HistoricalAuditsPostRequest' example: search: created_since: '2019-01-01T00:00:00Z' created_before: '2019-01-01T00:00:00Z' auditable_type: Feature auditable_id: 1007868956 components: schemas: HistoricalAuditsPostResponse: type: object properties: search_id: type: string example: '6776881149486782892' example: search_id: '6776881149486782892' HistoricalAuditsPostRequest: type: object properties: search: type: object properties: created_since: type: string example: '2019-01-01T00:00:00Z' created_before: type: string example: '2019-01-01T00:00:00Z' auditable_type: type: string example: Feature auditable_id: type: integer example: 1007868956 example: created_since: '2019-01-01T00:00:00Z' created_before: '2019-01-01T00:00:00Z' auditable_type: Feature auditable_id: 1007868956 example: search: created_since: '2019-01-01T00:00:00Z' created_before: '2019-01-01T00:00:00Z' auditable_type: Feature auditable_id: 1007868956 HistoricalAuditsGetResponse: type: object properties: historical_audits: type: array items: type: object properties: auditable_id: type: integer example: 1007868956 auditable_type: type: string example: Feature id: type: string example: '1049303076' name: type: string example: George Gently email: type: string example: no-reply@aha.io created_at: type: string example: '2019-01-01T00:00:00.000Z' updated_at: type: string example: '2019-01-01T00:00:00.000Z' dates_active: type: array items: type: string example: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' example: auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' example: - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' pagination: type: object properties: total_records: type: integer example: 3 total_pages: type: integer example: 1 current_page: type: integer example: 1 example: total_records: 3 total_pages: 1 current_page: 1 example: historical_audits: - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' - auditable_id: 1007868956 auditable_type: Feature id: '1049303076' name: George Gently email: no-reply@aha.io created_at: '2019-01-01T00:00:00.000Z' updated_at: '2019-01-01T00:00:00.000Z' dates_active: - '2019-01-01' - '2019-01-01' - '2019-01-01' - '2019-01-01' pagination: total_records: 3 total_pages: 1 current_page: 1 securitySchemes: OAuth2: type: oauth2 description: OAuth2 authentication with bearer tokens flows: authorizationCode: authorizationUrl: https://{account-domain}.aha.io/oauth/authorize tokenUrl: https://{account-domain}.aha.io/oauth/token scopes: {} ApiKeyAuth: type: http scheme: bearer description: API key authentication using Bearer token in Authorization header. Generate API keys at https://secure.aha.io/settings/api_keys CookieAuth: type: apiKey in: cookie name: session description: Cookie-based authentication for web browser integration