Excluding and including sources

A source rule names web sources a plagiarism check may or may not cite. Use exclude rules to drop your own site, a client's published pages or a mirror that would otherwise match every document, and include rules to check against one set of sources only. Rules are applied in code before matches are aligned, so a rule is a guarantee, not a suggestion.

The two lists

There are two places a rule can live, and a check applies both:

• The account list. Stored on the account, edited under Account, then Settings in the app or over /v1/source-rules, and applied to every check the account runs, from the app or the API.
• A single check. Sent as sourceRules on POST /v1/checks, applied to that check together with the account list, and stored on the check so you can read back what it ran with.

An exclude rule in either list removes matching sources. Once any include rule exists in either list, only sources matching an include rule are kept, with the excludes still applied on top. So exclude wins when both match, and the union of the two lists is what runs.

Rule shapes

Every rule has a mode (exclude or include), a kind, and a value.

Values are stored lowercased without a scheme or www., so https://www.Example.com/ and example.com are the same domain rule. A value that could match nothing (a path inside a domain rule, a pattern with fewer than three literal characters) is refused as 400 invalid_source_rule with a message that says why, at submission rather than in a thin report weeks later. An account holds up to 50 rules of up to 300 characters; a check may carry up to 50 of its own.

Managing the account list

List what is there. Every stored rule has an id you can address:

curl https://api.silvertext.com/v1/source-rules \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY"

{
  "rules": [
    { "id": "sr_k3j9x2m8q1w5", "mode": "exclude", "kind": "domain", "value": "example.com" }
  ],
  "count": 1,
  "limits": { "maxRules": 50, "maxValueLength": 300 }
}

Add one rule. A rule that already exists answers 200 with the existing rule; a new one answers 201:

curl -X POST https://api.silvertext.com/v1/source-rules \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "exclude", "kind": "hostname", "value": "docs.example.com" }'

Change a rule in place (the id stays), or delete it:

curl -X PATCH https://api.silvertext.com/v1/source-rules/sr_k3j9x2m8q1w5 \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "url", "value": "example.com/blog" }'

curl -X DELETE https://api.silvertext.com/v1/source-rules/sr_k3j9x2m8q1w5 \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY"

Replace the whole list in one call when you keep the source of truth on your side. Rules sent with their ids keep them; rules: [] clears the list:

curl -X PUT https://api.silvertext.com/v1/source-rules \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rules": [
        { "mode": "exclude", "kind": "domain", "value": "example.com" },
        { "mode": "include", "kind": "pattern", "value": "*.edu/*" }
      ] }'

Reading the list needs checks:read; adding, changing, replacing and deleting need checks:write.

Rules for one check

When the rules belong to the document rather than the account (checking a client's draft against everything except the client's own site, say), send them with the check:

curl -X POST https://api.silvertext.com/v1/checks \
  -H "Authorization: Bearer $SILVERTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "…",
    "sourceRules": [
      { "mode": "exclude", "kind": "domain", "value": "client-site.example" }
    ]
  }'

Outside JSON, sourceRules is a JSON-encoded string, the same way options is: a multipart or form field beside the file, or a query parameter when the raw body is the document. The check answers 202 as usual; a bad rule is refused as 400 before anything is reserved or charged. The finished check carries the rules it ran with as sourceRules.

Reading what was excluded

A finished report's meta.sourcesExcludedByRules counts the web sources the rules removed from that check. A count that is higher than you expect usually means a rule is broader than intended (a domain rule where a hostname was meant, or an include rule that narrowed the check to one site).

Which to use

• Your own pages, a mirror, a syndication partner: the account list, once.
• Anything that varies per document or per end user of your integration: sourceRules on the check.
• Both are fine together. The account list is the floor; a check can only add to it.