> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new audit event



## OpenAPI

````yaml post /org/{org}/auditctx/{contextName}
openapi: 3.0.1
info:
  title: Control Plane Audit API
  description: Copyright © 2026 Control Plane Corporation. All rights reserved.
  version: 1.0.0
servers:
  - url: https://audit.cpln.io/audit
security:
  - {}
  - serviceAccountKey: []
  - jwt: []
tags:
  - name: query
    description: Audit event queries
  - name: producer
    description: Audit event producer
externalDocs:
  url: https://docs.controlplane.com
  description: End-user documentation
paths:
  /org/{org}/auditctx/{contextName}:
    post:
      tags:
        - producer
      summary: Create a new audit event
      operationId: postEvent
      parameters:
        - $ref: '#/components/parameters/org'
        - $ref: '#/components/parameters/contextName'
        - $ref: '#/components/parameters/async'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditEvent'
      responses:
        '200':
          description: An audit event object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    org:
      name: org
      in: path
      required: true
      schema:
        type: string
    contextName:
      name: contextName
      in: path
      required: true
      schema:
        type: string
    async:
      name: async
      description: >-
        If true, don't wait for the forwarding audit service to send the event
        to the backend. This mode allows for processing new audit events at a
        higher volume.
      in: query
      required: false
      schema:
        type: boolean
        default: false
  schemas:
    AuditEvent:
      type: object
      required:
        - resource
      properties:
        id:
          type: string
          description: The event ID, assigned by the system
          example: 7f2195ac-e003-42a3-8324-d4bb1f11d10e
        eventTime:
          type: string
          description: >-
            The time of the event's occurrence. This can be anytime before the
            event is posted to the system.
          example: '2021-01-02T13:01:02.345Z'
        postedTime:
          type: string
          description: The time the event is posted to the system, assigned automatically
          example: '2021-01-02T13:01:03.123Z'
        receivedTime:
          type: string
          description: >-
            The time the event is received and processed by the system, assigned
            automatically
          example: '2021-01-02T13:01:03.159Z'
        requestId:
          type: string
          description: >-
            The identifier of the request, the event is associated with. It is
            not related to the event's identifier. There can be zero, or one or
            more audit events associated with the same request ID.
          example: d4e26a95-1988-4bf5-94fb-40d605cce0e9
        context:
          $ref: '#/components/schemas/Context'
        subject:
          $ref: '#/components/schemas/Subject'
        action:
          $ref: '#/components/schemas/Action'
        resource:
          $ref: '#/components/schemas/Resource'
        result:
          $ref: '#/components/schemas/Result'
    AuditCreateResponse:
      type: object
      properties:
        id:
          type: string
          example: '1234'
        message:
          type: string
          example: Published event with ID 1234 on primary transport
    Context:
      type: object
      properties:
        org:
          type: string
          description: >-
            The name of the posting organization, set based on the posting
            entity's organization.
          example: myorg
        name:
          type: string
          description: The audit context name.
          example: audit-context-1
        remoteIp:
          type: string
          example: 1.2.3.4
        eventSource:
          type: string
          example: system
        location:
          type: string
          description: The location/region where the event is created.
          example: aws-us-west-2
        gvcAlias:
          type: string
          example: gm0b1e3a1vxjj
        podId:
          type: string
          example: workload-00016-deployment-54b5b8f94f-jqkcn
        data:
          type: object
          description: Additional custom data about the event context
    Subject:
      type: object
      properties:
        email:
          type: string
          example: bob@company.com
        name:
          type: string
          example: Bob Johnson
        claims:
          type: object
          description: Additional optional claims about the subject
        data:
          type: object
          description: Additional optional data about the subject
    Action:
      type: object
      properties:
        type:
          type: string
          example: delete
        data:
          type: object
          description: Additional optional data about the action
    Resource:
      type: object
      properties:
        id:
          type: string
          example: dfedd8b9-7737-498a-883f-0162510c0d68
        name:
          type: string
          example: my-workload
        type:
          type: string
          example: workload
        data:
          type: object
          example:
            foo: bar
    Result:
      type: object
      properties:
        status:
          type: string
          example: OK
        message:
          type: string
          example: Object created successfully
    AuditError:
      type: object
      properties:
        error:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuditError'
    Unauthenticated:
      description: Unauthenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuditError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuditError'
  securitySchemes:
    serviceAccountKey:
      type: apiKey
      in: header
      name: Authorization
      description: Service account key can be used as API keys
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: IDP-provided token

````