Build with the API

Quality rules API

Create, list, change and delete rules, with every setting for each kind.

Quality rules over HTTP. What a rule is, and how to think about errors and warnings, is in the dashboard guide Quality rules. Here are the calls and every setting.

The seven kinds of rule

Kind	In plain words	Settings
`required_column`	The file must have this column.	—
`max_null_percent`	At most this share of the column may be empty.	`max`: 0 to 100
`type_is`	The column must be this kind of data.	`type`: `integer`, `number`, `boolean`, `date` or `string`; `maxInconsistentPercent`: 0 to 100 (default 0)
`min_value`	No number may be below this.	`min`
`max_value`	No number may be above this.	`max`
`unique`	No value in the column may repeat.	—
`max_duplicate_rows`	At most this many whole rows may repeat. This one is about the whole file, so it takes no column.	`max`

Rules look at a file's statistics, never its rows. They are about the shape and health of the data, so checking them never needs to read cell values.

Create a rule

POST/quality-rulesAdmins. An API key also needs the rules:write scope.

namestringrequired: What it is called in reports, up to 80 characters.
kindstringrequired: One of the seven kinds above. It can never be changed afterwards: delete the rule and make a new one.
columnNamestringoptional: The column it applies to. Required for every kind except max_duplicate_rows. Matched to the file's header ignoring case.
paramsobjectoptional: The settings for the kind, from the table above.
severityerror | warningoptional: Defaults to error. See below.
enabledbooleanoptional: Defaults to true. A disabled rule is kept but not checked.

curl https://gridline-data-analysis-app.duckdns.org/api/quality-rules \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emails are filled in",
    "kind": "max_null_percent",
    "columnName": "email",
    "params": { "max": 5 },
    "severity": "error"
  }'

Other endpoints:

GET /quality-rules: list your rules. Anyone in the company can read them, so an employee knows what an upload is checked against.
PATCH /quality-rules/{id}: change the name, column, settings (they replace the old ones), severity or whether it is enabled.
DELETE /quality-rules/{id}: remove it. Reports already built keep their result for it.

Errors and warnings

	Counts in the score	When it fails
`error`	Twice	Notifies the uploader and every admin.
`warning`	Once	Only lowers the score. Nobody is notified.

The notification names the rules that failed and the score. It never contains a value from the file.

When a rule does not apply

Your rules cover every upload, but your files are different from each other. A file with no amount column is not wrong for an amount rule, so such a rule is skipped for that file, not failed. A skipped rule counts for nothing in the score.

Limits

Plan	Rules you can keep
Free	3
Basic	25
Premium	No limit

Disabled rules count towards the limit. You can have at most 10 unique rules on any plan, because each is checked by remembering the values of its column. Going past a limit answers 409 with the reason. A downgrade that would leave you over the new plan's limit is refused until you delete some.