AngelCam event API

openapi: 3.0.0
info:
  version: 2026.06.11
  title: Angelcam active-service event API
  contact:
    email: support@angelcam.com
  x-logo:
    url: ./assets/logo-angelcam.svg
  description: 'Angelcam RESTful API — HTTPS only, JSON, all URLs require a trailing slash. See the [developer docs](/) for quickstart, authentication, and key concepts.

    '
servers:
- url: https://api.angelcam.com/v1
tags:
- name: event
  x-displayName: Events
  description: 'Events represent detections reported by cameras or sensors — typically motion detected by a camera or a trigger from an external sensor. Events are the building blocks for [RTS incidents](#tag/incidents) and camera timeline markers.


    ## Sending events to Angelcam

    When a camera or sensor detects something, it reports it to Angelcam by calling the event endpoint with its unique `hash` (found in the Angelcam dashboard or via the [Sensor](#tag/sensor) endpoints). Use `POST /v1/events/` in all cases where possible. A `GET /v1/events/` alternative exists solely for devices that are technically incapable of making POST requests (some older cameras). The rate limit for event submission is 10 requests per minute per hash.


    ## Listing events

    Pagination for event list endpoints works differently from other list endpoints: there is no `offset` parameter. Instead:

    - Use the `next` link in the response to move to the next page. - Pagination is one-directional (forward only). - Use the `start` and `end` filters to narrow down the time range.

    Events are returned ordered by `occurred_at` (newest first).

    '
paths:
  /cameras/{camera_id}/events/:
    get:
      operationId: camera-events
      summary: Retrieve camera event list
      tags:
      - event
      description: Retrieves list of events belonging to the specified camera
      parameters:
      - $ref: '#/components/parameters/cameraId'
      - name: start
        in: query
        description: 'Example: `2017-03-07T14:00:00Z`.'
        required: false
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        description: 'Example: `2017-03-07T16:00:00Z`.'
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: 'Limit result set. Example: `1`.'
        required: false
        schema:
          type: integer
          minimum: 1
      security:
      - OAuth2:
        - event_access
      - PersonalAccessToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
        '400':
          $ref: '#/components/responses/Error400InvalidParams'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
        '404':
          $ref: '#/components/responses/Error404NotFound'
  /events/:
    post:
      operationId: events-create
      summary: Create event
      tags:
      - event
      description: 'This endpoint has rate limiting in place. The endpoint will accept at most 10 requests per minute

        for a given hash (see [Nuts and bolts](#section/Angelcam-API/Nuts-and-bolts) for more details).

        '
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: event
              required:
              - hash
              properties:
                hash:
                  type: string
                  description: 'Event API hash (a unique token for each sensor found in My Angelcam dashboard or obtained

                    via Sensor Resource) - used to authenticate the request and pair the event with corresponding

                    sensor.

                    '
                title:
                  type: string
                occurred_at:
                  type: string
                  format: datetime
              example:
                hash: 50yxnlu2o2
      security: []
      responses:
        '201':
          description: Event was received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventObject'
        '400':
          description: The event hash is invalid or there's another error in the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Invalid'
        '429':
          description: The rate limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429TooManyRequests'
    get:
      operationId: events-create-get
      summary: Create event by get request
      tags:
      - event
      description: 'In cases when it''s not possible to send post request we allowed to create event by GET request. In general you should avoid using this method and rather prefer creating events via POST request.

        '
      parameters:
      - name: hash
        in: query
        required: true
        description: 'Event API hash (a unique token for each camera found in My Angelcam dashboard or obtained

          via Camera Resource) - used to authenticate the request and pair the event with corresponding

          camera.

          '
        example: 50yxnlu2o2
        schema:
          type: string
      - name: title
        in: query
        required: false
        schema:
          type: string
      security: []
      responses:
        '201':
          description: Event was received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventObject'
        '400':
          description: The event hash is invalid or there's another error in the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Invalid'
        '429':
          description: The rate limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429TooManyRequests'
components:
  parameters:
    cameraId:
      name: camera_id
      in: path
      required: true
      description: Camera ID
      example: 3
      schema:
        type: integer
        minimum: 1
  schemas:
    ErrorGeneric:
      type: object
      title: Error object
      properties:
        title:
          type: string
        detail:
          type: string
        status:
          type: integer
      required:
      - title
      - detail
      - status
    Error400InvalidParams:
      type: object
      title: Error 400 Invalid Parameters
      properties:
        title:
          type: string
        detail:
          type: object
        status:
          type: integer
      required:
      - title
      - detail
      - status
      example:
        title: invalid
        detail:
        - refresh_rate:
          - valid number is required.
          - Ensure this value is greater than 0.
        - max_width:
          - valid number is required.
          - Ensure this value is greater than or equal to 1.
        status: 400
    Error403PermissionDenied:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 403 Permission Denied
      example:
        title: permission_denied
        detail: You do not have permission to perform this action.
        status: 403
    Error429TooManyRequests:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 429 Too Many Requests
      example:
        title: rate_limited
        detail: The rate limit has been reached
        status: 429
    Error400Invalid:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 400 Bad Request
      example:
        title: invalid
        detail: Invalid hash
        status: 400
    EventObject:
      type: object
      title: Event object
      properties:
        camera:
          description: Camera ID
          nullable: true
          type: integer
        site:
          description: Site ID
          nullable: true
          type: integer
        title:
          description: Event title
          nullable: true
          type: string
        category:
          type: string
          description: event category
        source:
          type: string
          description: Name of event source
        occurred_at:
          type: string
          format: datetime
          description: Time when event occurred or was received by Angelcam
        received_at:
          type: string
          format: datetime
          description: Time when event was received by Angelcam
      required:
      - camera
      - site
      - title
      - category
      - source
      - received_at
      - occurred_at
      example:
        title: Door open
        camera: 20
        site: null
        source: smtp
        category: motion_detected
        received_at: '2018-10-24T11:21:59.000Z'
        occurred_at: '2018-10-24T11:21:39.000Z'
    EventListResponse:
      type: object
      title: Event list
      properties:
        count:
          type: integer
          minimum: 0
          description: Count of all events
        next:
          format: uri
          description: Next page from pagination
          nullable: true
          type: string
        previous:
          description: Previous page from pagination
          type: string
          nullable: true
        results:
          type: array
          description: List of events owned by the user
          items:
            $ref: '#/components/schemas/EventObject'
      required:
      - count
      - next
      - previous
      - results
    Error401Unauthorized:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 401 Unauthorized
      example:
        title: not_authenticated
        detail: Authentication credentials were not provided
        status: 401
    Error404NotFound:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 404 Not Found
      example:
        title: not_found
        detail: Not Found
        status: 404
  responses:
    Error403PermissionDenied:
      description: Missing permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403PermissionDenied'
    Error404NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404NotFound'
    Error401Unauthorized:
      description: Missing or invalid authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401Unauthorized'
    Error400InvalidParams:
      description: Query params are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400InvalidParams'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'See the Authentication section above for full documentation.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://my.angelcam.com/oauth/authorize/
          tokenUrl: https://my.angelcam.com/oauth/token/
          scopes:
            user_access: Permission to access user information
            user_delete: Permission to delete the current user account
            camera_access: Permission to list cameras and to get details of a specific camera
            camera_create: Permission to create cameras
            camera_manage: Permission to update cameras
            camera_delete: Permission to delete cameras
            camera_guest_access: Permission to access camera guest
            camera_guest_manage: Permission to manage camera guest
            public_cameras_access: Permission to access public cameras
            arrow_client_access: Permission to access Arrow clients
            arrow_client_manage: Permission to manage Arrow clients
            event_access: Permission to access events
            recording_access: Permission to access camera recordings
            recording_start_stop: Permission to start and stop recording on camera
            recording_clips_access: Permission to access recording clips
            recording_clips_create: Permission to create recording clips
            recording_clips_share: Permission to share recording clips
            sensor_access: Permission to list sensors and to get details of a specific sensor
            sensor_manage: Permission to create, update and delete sensors
            broadcasting_access: Permission to see general broadcasting information and access broadcasting streams
            broadcasting_start_stop: Permission to start and stop public broadcasting on camera
            client_access: Permission to list resellers clients and get details of a specific client
            client_create: Permission to create client account
            client_manage: Permission to update clients detail
            streams_detect: Permission to detect camera streams
            sites_access: Permission to access sites
            sites_manage: Permission to create, update and delete sites
            services_access: Permission to access available services
            trials_access: Permission to access available trials
            trials_activate: Permission to activate a trial
            active_services_access: Permission to access active services
            active_services_manage: Permission to manage active services
            orders_access: Permission to access orders
            messages_access: Permission to access RTS messages
            messages_manage: Permission to manage RTS messages
            incidents_access: Permission to access Incidents
            space_access: Permission to list and activate spaces
            space_permissions_access: Permission to view space permissions
        password:
          tokenUrl: https://api.angelcam.com/oauth/token/
          scopes:
            user_access: Permission to access user information
            user_delete: Permission to delete the current user account
            camera_access: Permission to list cameras and to get details of a specific camera
            camera_create: Permission to create cameras
            camera_manage: Permission to update cameras
            camera_delete: Permission to delete cameras
            camera_guest_access: Permission to access camera guest
            camera_guest_manage: Permission to manage camera guest
            arrow_client_access: Permission to access Arrow clients
            arrow_client_manage: Permission to manage Arrow clients
            event_access: Permission to access events
            recording_access: Permission to access camera recordings
            recording_start_stop: Permission to start and stop recording on camera
            recording_clips_access: Permission to access recording clips
            recording_clips_create: Permission to create recording clips
            recording_clips_share: Permission to share recording clips
            sensor_access: Permission to list sensors and to get details of a specific sensor
            sensor_manage: Permission to create, update and delete sensors
            broadcasting_access: Permission to see general broadcasting information and access broadcasting streams
            broadcasting_start_stop: Permission to start and stop public broadcasting on camera
            client_access: Permission to list resellers clients and get details of a specific client
            client_create: Permission to create client account
            client_manage: Permission to update clients detail
            streams_detect: Permission to detect camera streams
            sites_access: Permission to access sites
            sites_manage: Permission to create, update and delete sites
            services_access: Permission to access available services
            trials_access: Permission to access available trials
            trials_activate: Permission to activate a trial
            active_services_access: Permission to access active services
            active_services_manage: Permission to manage active services
            orders_access: Permission to access orders
            messages_access: Permission to access RTS messages
            messages_manage: Permission to manage RTS messages
            rts_settings_access: Permission to access RTS settings
            rts_settings_manage: Permission to manage RTS settings
            rts_arming_manage: Permission to arm and disarm RTS
            incidents_access: Permission to access Incidents
            space_access: Permission to list and activate spaces
            space_permissions_access: Permission to view space permissions
    PersonalAccessToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Enter your token as: `PersonalAccessToken {your-token}`

        '
x-tagGroups:
- name: General
  tags:
  - user
  - space
  - location
- name: Camera management
  tags:
  - camera
  - shared-camera
  - camera-guest
  - camera-stream-detection
  - arrow-clients
  - angelcameras
- name: Recording
  tags:
  - recording
  - stream-controls
  - shared-camera-recording
  - clip
  - shared-camera-clip
- name: Broadcasting
  tags:
  - broadcasting
  - public-camera
- name: Events & Sensors
  tags:
  - event
  - sensor
- name: Speaker management
  tags:
  - speakers
  - audio-message
- name: RTS
  tags:
  - incidents
  - rts_settings
  - rts_messages
  - rts_notification_methods
  - rts_notification_rules
- name: Billing
  tags:
  - service
  - active-service
  - order
- name: Clients
  tags:
  - client