Alerts

An alert is a fault //SCHEMA found in your catalog that only you can correct: a file refused at intake, bytes that contradict the hash their delivery declared, a console upload //SCHEMA could not match to one track. It is the console's Inbox, and the same list is here.

One alert per condition. Seeing the same problem again — a redelivery refused for the same reason — moves lastSeenAt and occurrences rather than adding an alert.
Blocking alerts hold something: the release stays pending until the problem is fixed. Warnings hold nothing.
Alerts close themselves when the problem is fixed — the right file lands at the same path, or is uploaded on the track — and are kept afterwards, so alerts(status: RESOLVED) answers "what was wrong with this release last month".
fix and related are typed targets with ids you can query, not URLs.

Titles, descriptions and target labels quote text your senders wrote, such as filenames. Render them as text, never as markup.

Operations

queryalerts
queryalertCounts
mutationdismissAlert
mutationmarkAlertsRead

The Alert object#

A problem in your catalog that only you can fix.

Attributes

alertPkInt!
Unique identifier.
kindAlertKind!
What kind of problem; see AlertKind.
severityAlertSeverity!
BLOCKING when something is held until it is fixed, WARNING when nothing is.
titleString!
One line. Quotes text your senders wrote; render it as text.
descriptionString!
What //SCHEMA saw, why it matters, and what to do. Quotes text your senders wrote; render it as text.
fixAlertTarget!
The thing that most likely needs correcting.
related[AlertTarget!]!
Everything else worth a link — the release, the delivery that raised it.
raisedAtDateTime!
When it was first raised.
lastSeenAtDateTime!
When the problem was last observed.
occurrencesInt!
How many times it has been observed.
readBoolean!
Whether the signed-in person has read it. Always false for an API key.
dismissableBoolean!
Whether dismissAlert may close it.
resolvedAtDateTimenullable
When it closed, if it has.
resolutionAlertResolutionnullable
How it closed, if it has.
dismissNoteStringnullable
The note given when it was dismissed.
deliveryMessagenullable
The Message that raised it, when there was one.

The AlertTarget object#

Something an alert links to. Typed, with ids, rather than a URL.

Attributes

kindAlertTargetKind!
What it points at.
releasePkIntnullable
The release, for RELEASE and TRACK.
resourcePkIntnullable
The track, for TRACK.
messagePkIntnullable
The delivery, for DELIVERY.
labelString!
A name for the link, such as a track's title and ISRC. Quotes text your senders wrote.

The AlertConnection object#

One page of alerts.

Attributes

nodes[Alert!]!
The alerts on this page.
endCursorStringnullable
Pass as after for the next page; null on the last page.
hasNextPageBoolean!
Whether there is another page.

The AlertCounts object#

Counts of your catalog's open alerts.

Attributes

openInt!
Open alerts.
blockingInt!
Open alerts that hold something.
unreadInt!
Open alerts the signed-in person has not read. Equal to open for an API key.

The AlertKind enum#

What kind of problem an alert is.

Values

FILE_REJECTED
A delivered file was refused — today, an audio master that is not lossless. Fixed when a lossless file lands at the same path, or is uploaded on the track.
HASH_MISMATCH
A file's bytes contradict the hash its delivery declared, so the track was failed rather than promoted. Fixed when the right bytes arrive.
AMBIGUOUS_CLAIM
A console delivery could not tell which file dropped ahead of it belongs to a track, and took none. Fixed when the track has its file.

The AlertSeverity enum#

Whether something is held because of an alert.

Values

BLOCKING
Something is held — a release stays pending — until it is fixed.
WARNING
Nothing is held, but the catalog is wrong or will degrade.

The AlertStatus enum#

Which alerts to list.

Values

OPEN
Not yet resolved.
RESOLVED
Fixed, dismissed or superseded.

The AlertResolution enum#

How an alert closed.

Values

FIXED
The problem cleared.
DISMISSED
Someone decided it needs no fix.
SUPERSEDED
What it was about was deleted.

The AlertTargetKind enum#

What an AlertTarget points at.

Values

RELEASE
A release.
TRACK
A track on a release.
DELIVERY
A delivered message.
DELIVERIES
Your deliveries in general, for a problem with no release yet — a file refused before any delivery named it.

List alerts#

queryalerts→AlertConnection!catalog_read

Your catalog's alerts, one page at a time. Open alerts list blocking ones first, then the most recently seen; resolved alerts list the most recently resolved first.

Arguments

statusAlertStatus!Default: OPEN
OPEN (the default) or RESOLVED.
kindAlertKind
Only alerts of this AlertKind.
releasePkInt
Only alerts about this release.
firstInt
At most this many, up to 200. Defaults to 50.
afterString
The previous page's endCursor.

Returns

An AlertConnection.

Request

query {
  alerts(first: 1) {
    nodes {
      alertPk
      kind
      severity
      title
      fix {
        kind
        releasePk
        resourcePk
        label
      }
      occurrences
    }
    endCursor
    hasNextPage
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  alerts(first: 1) {\n    nodes {\n      alertPk\n      kind\n      severity\n      title\n      fix {\n        kind\n        releasePk\n        resourcePk\n        label\n      }\n      occurrences\n    }\n    endCursor\n    hasNextPage\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        alerts(first: 1) {
          nodes {
            alertPk
            kind
            severity
            title
            fix {
              kind
              releasePk
              resourcePk
              label
            }
            occurrences
          }
          endCursor
          hasNextPage
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "alerts": {
      "nodes": [
        {
          "alertPk": 311,
          "kind": "FILE_REJECTED",
          "severity": "BLOCKING",
          "title": "“A1.mp3” was refused: it is not a lossless master",
          "fix": {
            "kind": "TRACK",
            "releasePk": 812,
            "resourcePk": 4471,
            "label": "Night Ferry (ISRC USS1Z2600042)"
          },
          "occurrences": 2
        }
      ],
      "endCursor": null,
      "hasNextPage": false
    }
  }
}

Count open alerts#

queryalertCounts→AlertCounts!catalog_read

How many alerts are open, how many of those are blocking, and how many the signed-in person has not read. The console's nav badge is blocking.

Arguments

None.

Returns

An AlertCounts.

Request

query {
  alertCounts {
    open
    blocking
    unread
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  alertCounts {\n    open\n    blocking\n    unread\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        alertCounts {
          open
          blocking
          unread
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "alertCounts": {
      "open": 3,
      "blocking": 2,
      "unread": 3
    }
  }
}

Dismiss an alert#

mutationdismissAlert→Alert!catalog_write

Close an open alert without fixing it, with a note saying why. Only an alert whose dismissable is true can be dismissed; a blocking alert is closed by its fix. A dismissed alert stays dismissed when the same problem is seen again.

Arguments

alertPkInt!required
The alert.
noteString!required
Why it needs no fix. Required, and kept with the alert.

Returns

The dismissed Alert.

Request

mutation {
  dismissAlert(alertPk: 318, note: "Archival recording; the cutoff is in the source.") {
    alertPk
    resolution
    dismissNote
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  dismissAlert(alertPk: 318, note: \"Archival recording; the cutoff is in the source.\") {\n    alertPk\n    resolution\n    dismissNote\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        dismissAlert(alertPk: 318, note: "Archival recording; the cutoff is in the source.") {
          alertPk
          resolution
          dismissNote
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "dismissAlert": {
      "alertPk": 318,
      "resolution": "DISMISSED",
      "dismissNote": "Archival recording; the cutoff is in the source."
    }
  }
}

Mark alerts read#

mutationmarkAlertsRead→Int!catalog_read

Mark alerts read for the signed-in person. Sessions only — an API key has no read state, and the call is refused. Ids that are not your catalog's alerts are ignored.

Arguments

alertPks[Int!]!required
The alerts, up to 500.

Returns

How many were newly marked read.

Request

mutation {
  markAlertsRead(alertPks: [311, 312])
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  markAlertsRead(alertPks: [311, 312])\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        markAlertsRead(alertPks: [311, 312])
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "markAlertsRead": 2
  }
}