Aha.io Historical Audits API
The Historical Audits API from Aha.io — 1 operation(s) for historical audits.
OpenAPI Specification
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