API docs by Redocly

Grand Shooting Events API (1.0.0)

Download OpenAPI specification:

Grand Shooting: help@grand-shooting.com URL: https://grand-shooting.com

Centralized event streaming API for the Grand Shooting ecosystem.

gs-stream-events collects events produced by company applications (Grand Shooting, Sourcing, Connect), stores them, and distributes them to authorized consumers through pull-based queues and a historical query API.

Authentication

Every /v1/* route requires an API key passed in the Authorization header:

Authorization: Bearer gs_live_xxxxxxxx...
  • Keys start with gs_live_ (production) or gs_test_ (test).
  • Each key carries scopes that determine the allowed operations: events:write, events:read, queues:read, queues:manage, keys:manage, or * (full access).
  • Some operations additionally require the superadmin role (queue management) or ownership of the resource (queue stats and alerts).
  • The full key is displayed only once, at creation time.

OAuth 2.0 (JWT) authentication is also accepted on the same header for internal integrations.

Rate limiting

Limits apply per account, per minute, depending on the route tier:

Tier Limit Routes
STRICT 10 req/min Key management, queue creation/updates, alert configuration
STANDARD 1,000 req/min Event publishing
RELAXED 5,000 req/min Reads: queries, queue polling, stats, alerts

Test keys (gs_test_) get one tenth of each limit. Every response includes the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; 429 responses also include Retry-After (seconds).

Consuming events: the pull pattern

Webhooks have been replaced by consumer queues (managed SQS). Each consumer gets a dedicated queue, fed in real time according to its filters (event types, applications, accounts):

  1. Receive — GET /v1/queues/{name}/messages with long-polling (up to 20 s wait, 10 messages max). Received messages become invisible for the duration of the visibilityTimeout (30 s by default).
  2. Process — on the consumer side.
  3. Acknowledge — DELETE /v1/queues/{name}/messages with the receiptHandles. An unacknowledged message becomes visible again after the visibilityTimeout and will be redelivered.

Unconsumed messages are deleted after the queue's retention period (7 days by default, 14 days max). Built-in monitoring automatically alerts on backlog, idle consumers, or retention-loss risk (see the Alerts section).

Pagination

POST /v1/events/query uses cursor pagination: the response contains cursor (an opaque internal identifier) and hasMore. Pass the received cursor back in the next request to get the following page.

Event type format

eventType has 2 or 3 dot-separated segments, each starting with a lowercase letter (letters, _, -): photo.uploaded, user.account.updated.

Health

Service health check.

Service health

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "1.0.0",
  • "apiVersion": "v1",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "environment": "production"
}

Events

Event publishing (single or batch) and querying of stored history (18-month hot storage retention).

Publish an event

Publishes a single event. Required scope: events:write. The caller must have access to the scope.accountId account. eventId and timestamp are generated automatically when omitted.

Authorizations:
ApiKey
Request Body schema: application/json
required
eventId
string <uuid>

Generated automatically when omitted

eventType
required
string^[a-z][a-z_-]*(\.[a-z][a-z_-]*){1,2}$

2 or 3 dot-separated lowercase segments

timestamp
string <date-time>

Event date (default = now)

required
object
application
required
string non-empty
version
required
string
environment
required
string
Enum: "development" "staging" "production"
required
object

Who triggered the event

required
string or number

String or number, normalized to a string

One of
string

String or number, normalized to a string

required
string or number
One of
string
role
string
required
object

What the event is about (determines access rights)

required
string or number
One of
string
resourceType
required
string
required
string or number
One of
string
required
object

Business content of the event

property name*
additional property
any
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",
  • "eventType": "photo.uploaded",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "source": {
    },
  • "actor": {
    },
  • "scope": {
    },
  • "payload": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "eventId": "string"
}

Publish a batch of events

Publishes up to 100 events in a single request. Required scope: events:write. Invalid events are rejected individually (errors field) without blocking the others; duplicate eventIds are silently ignored.

Authorizations:
ApiKey
Request Body schema: application/json
required
required
Array of objects (EventInput) <= 100 items
Array (<= 100 items)
eventId
string <uuid>

Generated automatically when omitted

eventType
required
string^[a-z][a-z_-]*(\.[a-z][a-z_-]*){1,2}$

2 or 3 dot-separated lowercase segments

timestamp
string <date-time>

Event date (default = now)

required
object
required
object

Who triggered the event

required
object

What the event is about (determines access rights)

required
object

Business content of the event

object

Responses

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "accepted": 0,
  • "inserted": 0,
  • "eventIds": [
    ],
  • "errors": [
    ]
}

Query event history

Searches stored events. Required scope: events:read. Results are restricted to the accounts accessible by the caller and sorted by descending date. The payloadFilter uses JSONB containment: {"orderId": "123"} matches any payload containing this key/value pair.

Authorizations:
ApiKey
Request Body schema: application/json
object
accountIds
Array of strings
eventTypes
Array of strings
object
from
string <date-time>
to
string <date-time>
object

JSONB containment on the payload

property name*
additional property
any
limit
integer
Default: 100
cursor
string

Opaque cursor returned by the previous page

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "timeRange": {
    },
  • "payloadFilter": { },
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "cursor": "string",
  • "hasMore": true
}

Consumer queues

Management of distribution queues (creation, filters, configuration). Creating, updating, listing all queues and deleting are restricted to the superadmin role.

Create a queue

Superadmin only. Required scope: queues:manage. Creates a distribution queue fed in real time according to its filters.

Authorizations:
ApiKey
Request Body schema: application/json
required
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Lowercase letters, digits and hyphens; starts and ends with a letter or digit

object (QueueFilters)

Event routing filters for the queue. An omitted array or ["*"] means "everything". Types accept the .* suffix (prefix match): photo.* matches photo.uploaded, photo.deleted…

eventTypes
Array of strings
applications
Array of strings
accountIds
Array of strings
object (QueueConfig)
maxMessages
integer [ 1 .. 10 ]
Default: 10

Max messages per receive

waitTimeSeconds
integer [ 0 .. 20 ]
Default: 20

Max long-polling duration

visibilityTimeout
integer [ 0 .. 43200 ]
Default: 30

Invisibility of received messages, in seconds

retentionPeriod
integer [ 60 .. 1209600 ]
Default: 604800

Message retention in seconds (7 days by default, 14 max)

Responses

Request samples

Content type
application/json
{
  • "name": "billing-events",
  • "filters": {
    },
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "billing-events",
  • "status": "pending",
  • "filters": {
    },
  • "config": {
    },
  • "stats": {
    },
  • "endpoints": {},
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List all queues

Superadmin only. Required scope: queues:manage.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "queues": [
    ]
}

Queue details

Required scope: queues:read.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "billing-events",
  • "status": "pending",
  • "filters": {
    },
  • "config": {
    },
  • "stats": {
    },
  • "endpoints": {},
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a queue

Superadmin only. Required scope: queues:manage. Updates the filters, configuration or status (active/paused).

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Request Body schema: application/json
required
object (QueueFilters)

Event routing filters for the queue. An omitted array or ["*"] means "everything". Types accept the .* suffix (prefix match): photo.* matches photo.uploaded, photo.deleted…

eventTypes
Array of strings
applications
Array of strings
accountIds
Array of strings
object (QueueConfig)
maxMessages
integer [ 1 .. 10 ]
Default: 10

Max messages per receive

waitTimeSeconds
integer [ 0 .. 20 ]
Default: 20

Max long-polling duration

visibilityTimeout
integer [ 0 .. 43200 ]
Default: 30

Invisibility of received messages, in seconds

retentionPeriod
integer [ 60 .. 1209600 ]
Default: 604800

Message retention in seconds (7 days by default, 14 max)

status
string
Enum: "active" "paused"

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "config": {
    },
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "billing-events",
  • "status": "pending",
  • "filters": {
    },
  • "config": {
    },
  • "stats": {
    },
  • "endpoints": {},
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a queue

Superadmin only. Required scope: queues:manage. Deletes the queue and all the messages it contains — irreversible.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Messages

Receiving (long-polling) and acknowledging messages from a queue. See "Consuming events: the pull pattern" in the introduction.

Receive messages (long-polling)

Required scope: queues:read. Waits up to waitTimeSeconds for messages to arrive. Received messages become invisible for visibilityTimeout: acknowledge them before it expires, otherwise they will be redelivered.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

query Parameters
maxMessages
integer [ 1 .. 10 ]
Default: 10
waitTimeSeconds
integer [ 0 .. 20 ]
Default: 20
visibilityTimeout
integer [ 0 .. 43200 ]

Default = queue configuration (30 s)

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "meta": {
    }
}

Acknowledge messages

Required scope: queues:read. Permanently deletes processed messages (10 max per request). Partial failures are detailed in failed.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Request Body schema: application/json
required
receiptHandles
required
Array of strings <= 10 items

Responses

Request samples

Content type
application/json
{
  • "receiptHandles": [
    ]
}

Response samples

Content type
application/json
{
  • "successful": [
    ],
  • "failed": [
    ]
}

Alerts

Automatic queue monitoring (every 5 minutes): idle consumer (idle_consumer), messages close to the retention limit (retention_risk), abnormal backlog (backlog). Notifications go to the operations team and, by email, to the recipients configured per queue or per account (cascade: queue → account → system defaults).

Queue health

Required scope: queues:read, restricted to the queue's owner account (or superadmin). Instantaneous statistics + current alert state.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "status": "pending",
  • "stats": {
    },
  • "retentionPeriod": 0,
  • "alertState": {
    }
}

Queue alert configuration

Required scope: queues:read, restricted to the owner account (or superadmin). Returns the queue's own configuration, the account defaults, and the resulting effective configuration.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Responses

Response samples

Content type
application/json
{
  • "queueName": "string",
  • "alertConfig": {
    },
  • "accountDefaults": {
    },
  • "effectiveConfig": {
    }
}

Configure a queue's alerts

Required scope: queues:manage, restricted to the owner account (or superadmin). Partial configuration accepted — omitted fields inherit from the account defaults, then the system defaults.

Authorizations:
ApiKey
path Parameters
name
required
string [ 3 .. 80 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example: billing-events

Queue name

Request Body schema: application/json
required
enabled
boolean
Default: true
object
maxOldestAgeRatio
number ( 0 .. 1 ]
Default: 0.5

Alert when the oldest message's age exceeds this fraction of the retention

maxIdleMinutes
integer [ 10 .. 10080 ]
Default: 120

Alert when no polls for this duration while messages are waiting

maxDepth
integer >= 1
Default: 100000

Alert beyond this number of waiting messages

recipients
Array of strings <email> <= 20 items [ items <email > ]

Email recipients for notifications

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "thresholds": {
    },
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{
  • "queueName": "string",
  • "alertConfig": {
    },
  • "effectiveConfig": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Alerts overview

Required scope: queues:read. Alert state of every queue of the caller's account (all queues for a superadmin).

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "queues": [
    ]
}

Account alert defaults

Required scope: queues:read.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "alertConfig": {
    },
  • "systemDefaults": {
    },
  • "effectiveConfig": {
    }
}

Set the account alert defaults

Required scope: queues:manage. Applies to every queue of the account that has no configuration of its own.

Authorizations:
ApiKey
Request Body schema: application/json
required
enabled
boolean
Default: true
object
maxOldestAgeRatio
number ( 0 .. 1 ]
Default: 0.5

Alert when the oldest message's age exceeds this fraction of the retention

maxIdleMinutes
integer [ 10 .. 10080 ]
Default: 120

Alert when no polls for this duration while messages are waiting

maxDepth
integer >= 1
Default: 100000

Alert beyond this number of waiting messages

recipients
Array of strings <email> <= 20 items [ items <email > ]

Email recipients for notifications

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "thresholds": {
    },
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "alertConfig": {
    },
  • "effectiveConfig": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z"
}

API keys

Creation, listing and revocation of API keys (keys:manage scope).

Create an API key

Required scope: keys:manage. The caller's role bounds what can be created (an admin creates admin/user keys for their own account; only a superadmin creates keys for other accounts). Outside production, only test keys are created. The full key is returned only at creation time.

Authorizations:
ApiKey
Request Body schema: application/json
required
name
required
string
role
string
Enum: "superadmin" "admin" "user"
scopes
Array of strings
expiresAt
string <date-time>
isTest
boolean
accountId
string

Superadmin only (key for another account)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "superadmin",
  • "scopes": [
    ],
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "isTest": true,
  • "accountId": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key": "gs_live_a1b2c3...",
  • "name": "string",
  • "scopes": [
    ],
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List API keys

Required scope: keys:manage. Visibility depends on the role: a user sees their own keys, an admin those of their account, a superadmin all of them.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Revoke an API key

Required scope: keys:manage. Immediate and permanent revocation (soft delete).

Authorizations:
ApiKey
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "message": "API key revoked"
}

Administration

Internal unversioned routes, protected by an administration secret distinct from API keys. Operations use only.