Update a use case

patchhttps://api.faraday.ai/v1/knowledgebase/use_cases/{use_case_id}

Save a new revision of a use case. Optimistic locking: pass back the
revision_id you read; if the server's current revision has moved past
it, the request is rejected with 409. Fields not present are left at
their current values.

Authentication

Bearer Authentication

Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.

Authorization: Bearer YOUR_TOKEN

path parameters

use_case_idstring<uuid>required

The UUID of a use case

Match pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Body

Fields to update on the existing use case

draftone of 2 types

Advisory flag marking the use case as a work in progress. While
true, no implementation guide is generated for it (see
generated_guide) and a review weighs the incomplete status
accordingly. Defau...

Properties of one of 2 types
One of:
boolean

Pass this value to overwrite the existing value.

Title: Overwrite
guideone of 2 types

Markdown implementation guide. Deprecated — guides are now
generated from the use case (see generated_guide); this
human-authored field is retained for backward compatibility.
Optional.

Properties of one of 2 types
One of:
string

Pass this value to overwrite the existing value.

Title: Overwrite
prefaceone of 2 types
Properties of one of 2 types
One of:
backgroundone of 2 types

Markdown. The pre-existing situation that motivated this use case.

Properties of one of 2 types
One of:
string

Pass this value to overwrite the existing value.

Title: Overwrite
problemone of 2 types

Markdown. The specific problem the client is trying to solve.

Properties of one of 2 types
One of:
string

Pass this value to overwrite the existing value.

Title: Overwrite
solutionone of 2 types

Markdown. How Faraday addresses the problem at a conceptual level.

Properties of one of 2 types
One of:
string

Pass this value to overwrite the existing value.

Title: Overwrite
revision_idstring<uuid>
technical_detailsone of 2 types

Markdown technical annex that the guide generator and the
configuration auditor consume: data sources and schemas, data
grain, stable/reference keys, blockers (e.g. hashed vs cleartext
identity), feature flags, and egress destinations. Optional.

Properties of one of 2 types
One of:
string

Pass this value to overwrite the existing value.

Title: Overwrite
titlestring

Responses

200The newly saved use case revision
applies_tostring

Computed property: what this use case applies to, taken from its
most recent review. Read-only; absent until a review has classified
it.

Allowed values: this_account, subaccounts
archived_atstring<date-time>

Set when this use case has been archived.

created_atstring<date-time>required
draftboolean

Advisory flag marking the use case as a work in progress. While
true, no implementation guide is generated for it (see
generated_guide) and a review weighs the incomplete status
accordingly. Defau...

enrollment_creates_resourcesboolean

Computed property: whether those enrollment steps create Faraday
resources in the account named by applies_to, taken from this use
case's most recent review. A knowledgebase is audited only when no
...

generated_guidestring

Computed property: the implementation guide generated from this
use case's preface and technical_details. Read-only, and empty
until a guide has been generated. A guide is generated automatically
...

generated_guide_statusobject

Computed property: the status of the most recent implementation-guide
generation for this use case, or absent if none has run. Read-only.
Generation happens automatically once a review judges the use ...

Properties of object
created_atstring<date-time>required
generated_atstring<date-time>

When generation completed.

idstring<uuid>required
statusstringrequired

pending while the guide is being generated, ready once it has
been generated (its Markdown is then on generated_guide), error
if generation failed (see status_error).

Allowed values: pending, ready, error
status_errorstring

Failure detail when status is error.

use_case_idstring<uuid>required
use_case_revision_idstring<uuid>required

The use case revision the guide expands.

guidestringdeprecated

Markdown implementation guide. Deprecated — guides are now
generated from the use case (see generated_guide); this
human-authored field is retained for backward compatibility.
Optional.

idstring<uuid>required
prefaceobjectrequired

The narrative framing of a use case. All three fields are optional
markdown blocks; an empty preface means the use case hasn't been written
up beyond its title and guide.

Properties of object
backgroundstring

Markdown. The pre-existing situation that motivated this use case.

problemstring

Markdown. The specific problem the client is trying to solve.

solutionstring

Markdown. How Faraday addresses the problem at a conceptual level.

provisioning_guideboolean

Computed property: whether enrolling or unenrolling a sub-client
requires a repeatable series of steps, taken from this use case's
most recent review. When true, a provisioning guide is generated for
...

resourcesarray[object]deprecated

Deprecated, and no longer maintained. Which resources serve a use
case is reported by the account's configuration audits instead:
see use_cases[].resources on AccountAudit.

Items of array[object]
resource_idstring<uuid>required
resource_typestringrequired

The Postgres table name of the linked resource — cohorts,
new_outcomes, targets, scopes, recommenders, rosters,
connections, source_tables, etc.

reviewobject

Computed property: the most recent review of this use case, or
absent if it has never been reviewed. Read-only; request a review
with POST /knowledgebase/use_cases/{use_case_id}/review.

Properties of object
adequateboolean

True if the use case is adequate for downstream generation and
auditing. Absent until status is ready.

applies_tostring

What this use case applies to, as classified by this review. Absent
when the review could not determine it (e.g. a stub) or until
status is ready.

Allowed values: this_account, subaccounts
created_atstring<date-time>required
enrollment_creates_resourcesboolean

Whether those enrollment steps create Faraday resources in the
account named by applies_to. Meaningful only when
provisioning_guide is true. A knowledgebase is audited only when no
use case sets t...

findingsarray[object]required

The blockers and recommendations, most important first.

Items of array[object]
severitystringrequired

blocker — the use case cannot be confidently turned into a correct
guide or audited until this is resolved. recommendation — the
guide can be written without it, but the use case is materially
better with it addressed.

Allowed values: blocker, recommendation
textstringrequired

What is missing or wrong, and what to add or fix. Plain text.

idstring<uuid>required
modelstring

The model used for the review.

provisioning_guideboolean

Whether enrolling or unenrolling a sub-client requires a repeatable
series of steps, as classified by this review. When true, a
provisioning guide is generated for this use case. Absent when the
revie...

reviewed_atstring<date-time>

When the review pass completed.

statusstringrequired

pending while the review is enqueued, ready once it has been
filled in, error if the review failed (see status_error).

Allowed values: pending, ready, error
status_errorstring

Failure detail when status is error.

summarystring

One or two sentences on the overall state. Markdown.

use_case_idstring<uuid>required
use_case_revision_idstring<uuid>required

The use case revision this review was requested against.

revision_idstring<uuid>required
technical_detailsstring

Markdown technical annex that the guide generator and the
configuration auditor consume: data sources and schemas, data
grain, stable/reference keys, blockers (e.g. hashed vs cleartext
identity), feature flags, and egress destinations. Optional.

titlestringrequired
400The request was invalid.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

401No API key was supplied.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

403Access to this resource was forbidden.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

404The requested resource ID was not found.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

409The request was formatted correctly, but conflicted with an existing resource.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

500An internal server error occurred.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

Tags

knowledgebase