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
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...

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. Not versioned — reflects the
latest generated guide at read time.

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.

guide_generationobject

Computed property: the most recent guide generation for this use
case, or absent if none has been requested. Read-only; request
generation with
`POST /knowledgebase/use_cases/{use_case_id}/generate_gu...

Properties of object
created_atstring<date-time>required
flavorstring

The kind of guide that was generated. A guide is generated for use
cases that provision resources programmatically across many
accounts; other configurations are aligned through account review
instead. Absent until status is ready.

generated_atstring<date-time>

When generation completed.

idstring<uuid>required
statusstringrequired

pending while the generation is enqueued, ready once the guide
has been generated (its Markdown is then on generated_guide),
error if generation failed or was declined (see status_error) —
f...

Allowed values: pending, ready, error
status_errorstring

Failure or refusal detail when status is error.

use_case_idstring<uuid>required
use_case_revision_idstring<uuid>required

The use case revision the guide expands.

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.

resourcesarray[object]

Computed property: every resource link declared via the
knowledgebase. Not versioned — reflects the live state of
use_case_resources at read time.

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.

created_atstring<date-time>required
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.

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
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
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
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
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
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
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