Skip to main content
POST/functions/{name}/triggers

Create Function Trigger

Attaches an EVENT trigger to the named function: it fires on writes to a collection.

Body (camelCase):

  • collection (required)
  • events (one or more of insert, update, delete, upsert)
  • an optional filter in the JSON-policy grammar (for example {"eq": ["resource.status", "active"]}) limits invocations to matching records; null fires on every matching write
  • enabled (default true)
  • logOkInvocations (default false)

Scheduled triggers are not created here: use POST /@{projectSlug}/forge/schedules.

Errors:

  • 404 K9O_FUNCTION_NOT_FOUND when the function does not exist or is retired
  • 404 K9O_COLLECTION_NOT_FOUND when the collection does not exist
  • 400 K9O_POLICY_UNKNOWN_OPERATOR for a filter operator outside the grammar

Requires PROJECT_ADMIN.

Parameters
name *path

The function's name.

A module's operation is named <module>:<operation>.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
One of: object
collection *string

The collection whose writes fire the trigger.

It must exist.

events *"insert" | "update" | "delete" | "upsert"[]

The kinds of write that fire the trigger, 1 to 4 of insert, update, delete and upsert.

filterany

A condition on the written record, as a JSON predicate in the policy grammar: {"<operator>": [arg, ...]} with eq, neq, gt, lt, gte, lte, contains, not_contains, in, not_in, and, or and not. resource.<field> reads a field of the record.

The trigger fires only when it matches.

Null or absent fires on every matching event.

One of: object
or: null
enabledboolean

Whether the trigger fires.

Default true.

logOkInvocationsboolean

Whether successful invocations are logged as well as failed ones.

Default false.

or: object
bucket *string

The bucket whose objects fire the trigger.

It must exist and must not be a system bucket, and you must be able to read it.

events *"object.created" | "object.deleted" | "object.expired"[]

The object events that fire the trigger, 1 to 3 of object.created (an upload, an overwrite included), object.deleted (a delete through the API) and object.expired (removed by the bucket's deleteAfterDays).

A function that receives object.deleted or object.expired can't read the object any more.

filterany

Conditions on the object event, all of which must hold: pathPrefix, a literal prefix of the object's path (no wildcards); contentType, an exact type such as image/png or a family such as image/*; sizeBytes, an inclusive { min, max } range.

Null or absent fires on every matching event.

One of: object
pathPrefixstring

Fire only for objects whose path starts with this, compared literally.

contentTypestring

Fire only for this content type, or this family when it ends in /*.

sizeBytesobject

Fire only for objects whose size is in this inclusive range, in bytes.

mininteger

The smallest size that fires, in bytes, inclusive.

maxinteger

The largest size that fires, in bytes, inclusive.

or: null
enabledboolean

Whether the trigger fires.

Default true.

logOkInvocationsboolean

Whether successful invocations are logged as well as failed ones.

Default false.

Responses
HTTPK9O CodeDescription
201Created
400K9O_INVALID_FIELD_VALUEThe project slug, the function name or the collection name is not a valid identifier.
400K9O_POLICY_UNKNOWN_OPERATORThe filter uses an operator outside the JSON-policy grammar.
401K9O_UNAUTHENTICATEDThe caller presented no authenticated session.
403K9O_ACCESS_DENIEDThe caller has no access to this project.
403K9O_IAM_POLICY_DENIEDThe bound IAM policy ceiling denies creating function triggers; the default floor is PROJECT_ADMIN.
404K9O_FUNCTION_NOT_FOUNDNo function with that name exists in this project, or it is retired.
404K9O_COLLECTION_NOT_FOUNDThe collection named for the trigger does not exist in this project.
Response body (201)
data *object

A function trigger: the function runs when a matching write lands in the collection, or a matching object event happens in the bucket.

id *string <uuid>

The trigger's id, a UUID.

functionName *string

The function the trigger runs.

collection *any

The collection whose writes fire the trigger; null on a bucket trigger.

One of: string
or: null
bucket *any

The bucket whose object events fire the trigger; null on a collection trigger.

One of: string
or: null
events *any[]

The events that fire the trigger: insert, update, delete and upsert on a collection; on a bucket, object.created (an upload, an overwrite included), object.deleted (a delete through the API) and object.expired (removed by the bucket's deleteAfterDays).

A function that receives object.deleted or object.expired can't read the object any more.

One of: "insert" | "update" | "delete" | "upsert"
or: "object.created" | "object.deleted" | "object.expired"
filter *any

The condition an event must match: a record predicate on a collection trigger, object conditions on a bucket trigger.

Null when the trigger fires on every matching event.

One of: object
or: null
enabled *boolean

Whether the trigger fires.

logOkInvocations *boolean

Whether successful invocations are logged as well as failed ones.

createdAt *string <date-time>

When the trigger was created.

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.functions.triggers.create('greet', {
  collection: 'products',
  events: ['insert', 'update'],
  filter: {
    eq: ['resource.status', 'active']
  },
  enabled: true,
  logOkInvocations: false
})

Showing example in TypeScript

Request example
{
  "collection": "products",
  "events": [
    "insert",
    "update"
  ],
  "filter": {
    "eq": [
      "resource.status",
      "active"
    ]
  },
  "enabled": true,
  "logOkInvocations": false
}
Response example (201)
{
  "data": {
    "id": "string",
    "functionName": "string",
    "collection": "string",
    "bucket": "string",
    "events": [
      "insert"
    ],
    "enabled": false,
    "logOkInvocations": false,
    "createdAt": "string"
  }
}

More in Compute & Automation