Monitors

Create Monitor

Watch any data endpoint on a schedule and email up to three addresses what is new. The monitor runs once right away to record what already matches (the baseline) and sends a welcome email; from then on every run reports only what appeared since the last one: on a search, its new results; on a lookup of one record, the values that changed (each with what it was before) and any new item in its lists, such as a new action on a case. With schedule.cadence: "source" (the default) each run starts after the endpoint's own refresh has completed, so a daily source is checked once a day, right after new data lands; an endpoint served live has no refresh to follow and runs daily or weekly instead. Each run spends the same credits as one request to the endpoint. An organization may have up to 20 monitors.

post/monitors

Request

  • Base URL: https://api.croma.run
  • URL: https://api.croma.run/monitors
  • Auth: HTTP bearer

Headers

Idempotency-Keystring
Example:0f8e9a42-6b7c-4d1e-9a3f-2c5d7e8f9a0b

Optional client-chosen key for this request (any string up to 255 characters, e.g. a UUID). Every Croma operation is an idempotent lookup: repeating a request with the same body returns the same result and creates nothing, so retrying after a timeout or network failure is always safe. The key is echoed back in the Idempotency-Key response header so you can correlate a retry with its first attempt. Each attempt that reaches the API counts against the rate limit.

Request body

namestring required
endpointstring required

The endpoint to watch, by path or catalog id. Only endpoints with monitorable: true in /catalog are accepted: every data source, served from a Croma dataset or queried live. A search reports its new results; a lookup (one case, company, vehicle or person) reports what changed in that record.

queryobject

The request body the monitor sends to the endpoint, validated exactly as a direct request would be. page and per_page are not allowed.

recipientsstring[] required

Up to three addresses that receive the results.

notify'always' | 'on_new'

always sends an email on every run, including one that found nothing new; on_new only when there is something to report.

language'es' | 'en'

Language of the emails.

relevancestring nullable

Optional instruction, in plain language, that filters new results by relevance before they are sent (e.g. "solo avisos sobre suspensión o caducidad del título"). Results the filter discards stay available under GET /monitors/{id}/matches?relevant=false.

Example request

{
  "name": "Contrato AD9-111",
  "endpoint": "/co/anm/notices-search/v1",
  "query": {
    "title_number": "AD9-111"
  },
  "schedule": {
    "at": "08:00",
    "timezone": "America/Bogota"
  }
}

Response

The monitor, with its compiled schedule and next run.

Example response

{
  "data": {
    "id": "mon_5f1c2c0a-9d1e-4a3b-8c7d-1e2f3a4b5c6d",
    "endpoint": {
      "id": "anm-notices-search",
      "path": "/co/anm/notices-search/v1",
      "source": "ANM"
    },
    "schedule": {
      "cron": "30 7 * * *"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.