Scope Intelligence

Check whether a requested change is within an agreed statement of work, excluded, or needs a change request.

Endpoint

POST https://kovca.io/api/v1/scope/check

Authenticate with your API key in the Authorization: Bearer header. Send JSON with Content-Type: application/json; bodies are limited to 16 KB.

Each deliverable, acceptance criterion, amendment, exclusion, and assumption you send is checked against the request separately, and every reference in the result quotes your agreement exactly. This is an advisory classification, not a legally binding interpretation. Similar wording is never treated as proof of inclusion, and ambiguous agreements return uncertain. Send text; PDF parsing isn't supported.

Request body

Field	Type	Description
statement_of_work	string, required	The agreement text, up to 8,000 characters and 40 sentences.
requested_change	string, required	The new request or change, up to 2,000 characters.
deliverables	string[], optional	Up to 30. Without them, statement_of_work sentences are checked instead.
exclusions, assumptions, acceptance_criteria	string[], optional	Up to 30 each, 500 characters per item.
amendments	object[], optional	Up to 20 approved amendments: { id?, text }. An amendment covering the request supersedes exclusions.

Example request

{
  "statement_of_work": "Contoso will redesign and build the customer portal for Fabrikam, including account management and order history pages.",
  "deliverables": [
    "Responsive web portal with login, account settings, and order history",
    "Integration with Fabrikam's existing order API",
    "Two rounds of design revisions"
  ],
  "exclusions": [
    "Native mobile applications",
    "Data migration from the legacy portal"
  ],
  "assumptions": [
    "Fabrikam provides API documentation and a staging environment",
    "English-language content only"
  ],
  "requested_change": "Can you also build iOS and Android apps with the same features?"
}

Response

200 OK

{
  "request_id": "req_Np2wK7rTx4LmQ9vB",
  "status": "requires_change_request",
  "recommended_action": "initiate_change_request",
  "applicable_requirements": [],
  "potential_conflicts": [
    {
      "text": "Native mobile applications",
      "source": "exclusions[0]",
      "relation": "excludes"
    }
  ],
  "new_deliverable": true,
  "missing_information": [
    "acceptance_criteria"
  ]
}

Field	Type	Description
request_id	string	Unique ID for this request.
status	"within_scope" \| "potentially_out_of_scope" \| "requires_change_request" \| "uncertain"	See below.
recommended_action	"proceed" \| "clarify_scope" \| "review_contract" \| "initiate_change_request"	See below.
applicable_requirements	object[]	Agreement items that cover the request: { text (quoted exactly), source, relation (includes or partially_includes) }.
potential_conflicts	object[]	Exclusions and assumptions the request runs into: { text, source, relation (excludes or conflicts_with_assumption) }.
new_deliverable	boolean \| null	Whether the request asks for something the agreement doesn't describe; null when unclear.
missing_information	"deliverables" \| "exclusions" \| "acceptance_criteria"[]	Structured agreement content that wasn't sent.

Statuses (first match wins)

An approved amendment covers the request → within_scope, proceed.
A deliverable covers it but an exclusion rules it out, or an exclusion might apply → uncertain, review_contract.
An exclusion rules it out → requires_change_request, initiate_change_request.
It contradicts an assumption → potentially_out_of_scope, review_contract.
It might affect an assumption → uncertain, clarify_scope.
A deliverable, acceptance criterion, or amendment covers it → within_scope, proceed.
Only a general statement-of-work sentence covers it → uncertain, clarify_scope.
It asks for a new deliverable → potentially_out_of_scope, initiate_change_request.
Otherwise → uncertain, clarify_scope.

Amended scope

Request

{
  "statement_of_work": "Contoso will redesign and build the customer portal for Fabrikam, including account management and order history pages.",
  "deliverables": [
    "Responsive web portal with login, account settings, and order history",
    "Integration with Fabrikam's existing order API",
    "Two rounds of design revisions"
  ],
  "exclusions": [
    "Native mobile applications",
    "Data migration from the legacy portal"
  ],
  "assumptions": [
    "Fabrikam provides API documentation and a staging environment",
    "English-language content only"
  ],
  "amendments": [
    {
      "id": "CR-3",
      "text": "Data migration of active customer accounts from the legacy portal is added to scope."
    }
  ],
  "requested_change": "Please migrate our active customer accounts from the old portal."
}

Code

curl https://kovca.io/api/v1/scope/check \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "statement_of_work": "Contoso will redesign and build the customer portal for Fabrikam, including account management and order history pages.",
  "deliverables": [
    "Responsive web portal with login, account settings, and order history",
    "Integration with Fabrikam'\''s existing order API",
    "Two rounds of design revisions"
  ],
  "exclusions": [
    "Native mobile applications",
    "Data migration from the legacy portal"
  ],
  "assumptions": [
    "Fabrikam provides API documentation and a staging environment",
    "English-language content only"
  ],
  "requested_change": "Can you also build iOS and Android apps with the same features?"
}'

Errors

400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed. The message names the field.
413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

Advisory only; not legal advice or a contract interpretation.
Only the agreement text you send is considered. Send amendments to have them taken into account.
Inclusion is confirmed only by itemized content (deliverables, acceptance criteria, amendments), not by a general statement-of-work sentence.
Request data is processed to produce the result and is not stored by Kovca.