openapi: 3.0.2 info: title: Annotations API description: >- Use annotations to label specific points in time in your charts with a description. contact: url: https://mixpanel.com/get-support license: name: MIT url: https://opensource.org/licenses/MIT version: 1.0.0 servers: - url: https://{regionAndDomain}.com/api/app description: Mixpanel's application API server. variables: regionAndDomain: default: mixpanel enum: - mixpanel - eu.mixpanel - in.mixpanel description: | The server location to be used: * `mixpanel` - The default (US) servers used for most projects * `eu.mixpanel` - EU servers if you are enrolled in EU Data Residency * `in.mixpanel` - India servers if you are enrolled in India Data Residency security: - ServiceAccount: [] tags: - name: Create Annotation description: Create an annotation for a project - name: Delete Annotation description: Delete annotation for a project - name: Retrieve Annotations description: List all annotations for the project - name: Update Annotation description: Change an existing annotations paths: /projects/{projectId}/annotations: parameters: - in: path name: projectId schema: type: integer required: true description: 'Your project id (eg: 12345)' get: operationId: list-all-annotations-for-project parameters: - in: query name: fromDate schema: type: string description: >- The date in yyyy-mm-dd format to begin querying from. This date is inclusive. required: false - in: query name: toDate schema: type: string description: The date in yyyy-mm-dd format to query to. This date is inclusive. required: false tags: - Retrieve Annotations summary: List Annotations description: List all annotations in a project. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListAnnotationsResponse' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error post: operationId: create-annotation requestBody: required: true content: application/json: schema: properties: date: $ref: '#/components/schemas/InputDate' description: $ref: '#/components/schemas/InputDescription' tags: $ref: '#/components/schemas/TagIds' tags: - Create Annotations summary: Create Annotations description: Create an Annotation. Requires a role of at least Analyst. responses: '201': description: Success content: application/json: schema: $ref: '#/components/schemas/GetAnnotationsResponse' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error /projects/{projectId}/annotations/{annotationId}: parameters: - in: path name: projectId schema: type: integer required: true description: 'Your project id (eg: 12345)' - name: annotationId in: path description: The id of the annotation required: true schema: type: number get: operationId: get-annotation tags: - Retrieve Annotations summary: Get Annotation description: Get an Annotation responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetAnnotationsResponse' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error patch: operationId: patch-annotation tags: - Patch Annotation summary: Patch Annotation description: Patch an Annotation. Requires a role of at least Analyst. requestBody: required: true content: application/json: schema: properties: description: $ref: '#/components/schemas/InputDescription' tags: $ref: '#/components/schemas/TagIds' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetAnnotationsResponse' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error delete: operationId: delete-annotation tags: - Delete Annotation summary: Delete Annotation description: Delete an Annotation. Requires a role of at least Analyst. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeleteAnnotationsResponse' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error /projects/{projectId}/annotations/tags: parameters: - in: path name: projectId schema: type: integer required: true description: 'Your project id (eg: 12345)' get: operationId: get-annotation-tags tags: - Get Annotation tags description: >- Get all tags that have been added to at least one annotation. Requires a role of at least Analyst summary: Get Annotation Tags responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetAnnotationTagsResponse' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error post: operationId: create-annotation-tag tags: - Create Annotation tag description: >- Creates a new tag using the provided name. Requires a role of at least Analyst summary: Create Annotation Tag requestBody: required: true content: application/json: schema: properties: name: $ref: '#/components/schemas/TagName' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AnnotationTag' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Details about the error that occurred status: type: string enum: - error components: securitySchemes: ServiceAccount: type: http scheme: basic description: Service Account ProjectSecret: type: http scheme: basic description: Project Secret OAuthToken: type: http scheme: bearer description: OAuth Token schemas: GetAnnotationsResponse: title: GetAnnotationsResponse description: A JSON response object containing an annotation' type: object additionalProperties: false required: - status - results properties: status: $ref: '#/components/schemas/ResponseStatus' results: $ref: '#/components/schemas/AnnotationsEntry' DeleteAnnotationsResponse: title: DeleteAnnotationsResponse description: A JSON response object containing the id of the deleted annotation' type: object additionalProperties: false required: - status - results properties: status: $ref: '#/components/schemas/ResponseStatus' results: type: object properties: id: type: number description: The id of the deleted annotation ListAnnotationsResponse: title: ListAnnotationsResponse description: A JSON response object containing all annotations in the project' type: object additionalProperties: false required: - status - results properties: status: $ref: '#/components/schemas/ResponseStatus' results: type: array items: $ref: '#/components/schemas/AnnotationsEntry' AnnotationsEntry: title: AnnotationsEntry description: Representation of a single annotation type: object additionalProperties: false properties: date: $ref: '#/components/schemas/InputDate' description: $ref: '#/components/schemas/InputDescription' id: type: number user: $ref: '#/components/schemas/UserInfo' tags: type: array items: $ref: '#/components/schemas/SimpleTag' SimpleTag: title: SimpleTag description: Basic info about an Annotation Tag type: object properties: id: type: number name: type: string TagIds: title: TagIds description: The ids of the tags to be added to the annotation type: array items: type: number UserInfo: title: UserInfo description: Info about the creator of the annotation type: object properties: id: type: number first_name: example: John type: string last_name: example: Smith type: string GetAnnotationTagsResponse: title: GetAnnotationTagsResponse description: The list of annotation tags that have been created type: array items: $ref: '#/components/schemas/AnnotationTag' AnnotationTag: title: AnnotationTag description: An annotation tag type: object properties: id: type: number name: type: string project_id: type: number has_annotations: type: boolean description: whether the tag is currently attached to any annotations TagName: type: string description: The text that will be shown when the tag is added to an annotation InputDate: type: string description: A string representation of a date in "YYYY-MM-DD HH:mm:ss" format example: '2022-02-15 12:00:00' InputDescription: type: string description: The text that will be shown when looking at the annotation example: Something interesting happened! ResponseStatus: type: string description: The status of the response example: ok