Automation — MDDB API

Triggers, crons, and webhook targets for automated workflows

List automation rules #

GET /v1/automation

Returns all automation rules (webhooks, triggers, crons). Optionally filter by type, or (2.18.11) by collection to list the sources syncing into it. Every sync and backup carries lastResult.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
type	query	string	Filter by rule type One of "webhook", "trigger", "cron".
collection	query	string	(2.18.11) Only the rules acting on this collection — the syncs writing to it and the triggers watching it

Responses #

Status	Description	Body
200	List of automation rules	object (application/json)
400	Automation is not initialized	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Create automation rule #

POST /v1/automation

Create a new webhook target, trigger, or cron rule.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: AutomationRule

{
  "backup": {
    "bucket": "string",
    "collections": [
      "*"
    ],
    "keep": 0,
    "path": "string",
    "prefix": "mddb-",
    "storageConfig": {
      "accessKey": "AKIAIOSFODNN7EXAMPLE",
      "bucket": "my-mddb-bucket",
      "endpoint": "s3.amazonaws.com",
      "prefix": "mddb/",
      "region": "us-east-1",
      "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "useTLS": true
    },
    "target": "local"
  },
  "collection": "string",
  "conditionLogic": "and",
  "enabled": true,
  "events": [
    "insert"
  ],
  "lastResult": {
    "added": 0,
    "at": 0,
    "deleted": 0,
    "durationMs": 0,
    "error": "string",
    "failed": 0,
    "status": "success",
    "unchanged": 0,
    "updated": 0
  },
  "method": "POST",
  "name": "string",
  "query": "string",
  "schedule": "string",
  "searchType": "fts",
  "sentimentEnabled": false,
  "sentimentMax": 0,
  "sentimentMin": 0,
  "sync": {
    "bucket": "string",
    "collection": "string",
    "lang": "string",
    "maxBytes": 10485760,
    "maxDocuments": 1000,
    "prefix": "string",
    "prune": false,
    "source": "sitemap",
    "storageConfig": {
      "accessKey": "AKIAIOSFODNN7EXAMPLE",
      "bucket": "my-mddb-bucket",
      "endpoint": "s3.amazonaws.com",
      "prefix": "mddb/",
      "region": "us-east-1",
      "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "useTLS": true
    },
    "url": "https://example.com/",
    "urls": [
      "https://example.com/"
    ]
  },
  "threshold": 0,
  "triggerId": "string",
  "type": "webhook",
  "url": "string",
  "webhookId": "string"
}

Responses #

Status	Description	Body
201	Rule created	AutomationRule (application/json)
400	Validation error
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}

Get automation rule #

GET /v1/automation/{id}

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string

Responses #

Status	Description	Body
200	Automation rule	AutomationRule (application/json)
404	Not found
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Update automation rule #

PUT /v1/automation/{id}

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string

Request body #

Required.

Content type application/json: AutomationRule

{
  "backup": {
    "bucket": "string",
    "collections": [
      "*"
    ],
    "keep": 0,
    "path": "string",
    "prefix": "mddb-",
    "storageConfig": {
      "accessKey": "AKIAIOSFODNN7EXAMPLE",
      "bucket": "my-mddb-bucket",
      "endpoint": "s3.amazonaws.com",
      "prefix": "mddb/",
      "region": "us-east-1",
      "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "useTLS": true
    },
    "target": "local"
  },
  "collection": "string",
  "conditionLogic": "and",
  "enabled": true,
  "events": [
    "insert"
  ],
  "lastResult": {
    "added": 0,
    "at": 0,
    "deleted": 0,
    "durationMs": 0,
    "error": "string",
    "failed": 0,
    "status": "success",
    "unchanged": 0,
    "updated": 0
  },
  "method": "POST",
  "name": "string",
  "query": "string",
  "schedule": "string",
  "searchType": "fts",
  "sentimentEnabled": false,
  "sentimentMax": 0,
  "sentimentMin": 0,
  "sync": {
    "bucket": "string",
    "collection": "string",
    "lang": "string",
    "maxBytes": 10485760,
    "maxDocuments": 1000,
    "prefix": "string",
    "prune": false,
    "source": "sitemap",
    "storageConfig": {
      "accessKey": "AKIAIOSFODNN7EXAMPLE",
      "bucket": "my-mddb-bucket",
      "endpoint": "s3.amazonaws.com",
      "prefix": "mddb/",
      "region": "us-east-1",
      "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "useTLS": true
    },
    "url": "https://example.com/",
    "urls": [
      "https://example.com/"
    ]
  },
  "threshold": 0,
  "triggerId": "string",
  "type": "webhook",
  "url": "string",
  "webhookId": "string"
}

Responses #

Status	Description	Body
200	Rule updated	AutomationRule (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
404	The thing the request names does not exist.	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

404 example (application/json)

{
  "error": "not found"
}

413 example (application/json)

{
  "error": "request body too large"
}

Delete automation rule #

DELETE /v1/automation/{id}

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string

Responses #

Status	Description	Body
200	Rule deleted
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
404	The thing the request names does not exist.	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

404 example (application/json)

{
  "error": "not found"
}

Run a sync or backup rule now #

POST /v1/automation/{id}/run

(2.18.11) Runs a cron rule's sync or backup at once, through the code its schedule fires — logged in the automation log, announced on the jobs SSE stream, firing its webhook — and sets lastRun. A disabled rule runs too. The run goes on in the background; follow jobId on GET /v1/jobs/stream. Needs a global administrator.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string

Responses #

Status	Description	Body
202	The run started	AutomationRun (application/json)
400	The rule has no sync or backup	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
404	No such rule	ErrorResponse (application/json)
405	Method not allowed (POST only)	ErrorResponse (application/json)
409	The previous run of the rule is still going; the skip is logged	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)
503	The server runs no cron scheduler (MDDB_CRONS is off)	ErrorResponse (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Test trigger (dry run) #

POST /v1/automation/{id}/test

Execute a trigger's search and return matching documents without firing the webhook.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string

Responses #

Status	Description	Body
200	Test results	object (application/json)
400	Not a trigger rule (only triggers can be tested), or the test failed	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
404	The thing the request names does not exist.	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

404 example (application/json)

{
  "error": "not found"
}

List automation execution logs #

GET /v1/automation-logs

Returns automation execution logs ordered newest-first with cursor-based pagination. Requires MDDB_AUTOMATION_LOGS != "disable".

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
limit	query	integer	Max entries per page Default 50. Minimum 1. Maximum 500.
cursor	query	string	Pagination cursor from previous response
ruleId	query	string	Filter by rule ID
status	query	string	Filter by execution status One of "success", "error", "skipped".

Responses #

Status	Description	Body
200	Automation logs	object (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
404	Automation logs are disabled	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}