Replace recipe organization

PUT

/api/v1/recipes/{id}/organization

curl --request PUT \
  --url http://127.0.0.1:8080/api/v1/recipes/example/organization \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "book_membership": [ { "book_id": "example", "member": true, "revision": 1 } ], "facet_ids": [ "example" ], "sources": [ { "accessed_at": "2026-04-15T12:00:00Z", "attribution": "example", "id": "example", "kind": "url", "original_title": "example", "page_end": 1, "page_start": 1, "publication_book_id": "example", "url": "example" } ], "tag_ids": [ "example" ], "user_state": { "favorite": true, "personal_note": "example", "preferred_scale": "example", "preferred_yield": "example", "preferred_yield_assertion": 1, "rating": 1 } }'

• A local instance on its default listener.

Replaces tags, categories, personal state, and provenance, and applies any named book membership changes in the same transaction.

Authorizations

• bearerToken
• browserSession

Parameters

Path Parameters

id

required

string

Header Parameters

If-Match

string

Request Body^required

Media typeapplication/json

object

book_membership

Book membership changes applied in the same transaction

Array<object> | null

<= 100 items

object

book_id

required

string

>= 1 characters

member

required

True to place the recipe in the book, false to take it out

boolean

revision

required

Book revision this change expects

integer format: int64

>= 1

facet_ids

required

Array<string> | null

<= 100 items

sources

required

Array<object> | null

<= 100 items

object

accessed_at

string format: date-time

attribution

string

id

string

kind

required

string

Allowed values: url publication other

original_title

string

page_end

integer format: int64

page_start

integer format: int64

publication_book_id

string

url

string

tag_ids

required

Array<string> | null

<= 100 items

user_state

required

object

favorite

required

boolean

personal_note

string

<= 1000000 characters

preferred_scale

Preferred batch as an exact factor, for a yield that is not a number

string

<= 128 characters /^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

preferred_yield

Preferred yield as an exact amount of the recipe’s own yield

string

<= 128 characters /^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

preferred_yield_assertion

Position in the recipe’s yields of the yield this reader shows first and scales by. It does not reorder the recipe’s yields.

integer format: int64

<= 99

rating

integer format: int32

>= 1 <= 5

Responses

200

OK

Media typeapplication/json

object

facet_ids

required

Array<string> | null

library_entry_id

required

Identifier of the organized entry in the local Savorum library

string

revision

required

integer format: int64

sources

required

Array<object> | null

object

accessed_at

string format: date-time

attribution

string

id

string

kind

required

string

Allowed values: url publication other

original_title

string

page_end

integer format: int64

page_start

integer format: int64

publication_book_id

string

url

string

tag_ids

required

Array<string> | null

updated_at

required

string format: date-time

user_state

required

object

favorite

required

boolean

personal_note

string

<= 1000000 characters

preferred_scale

Preferred batch as an exact factor, for a yield that is not a number

string

<= 128 characters /^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

preferred_yield

Preferred yield as an exact amount of the recipe’s own yield

string

<= 128 characters /^([1-9][0-9]*|[1-9][0-9]*/[1-9][0-9]*)$/

preferred_yield_assertion

Position in the recipe’s yields of the yield this reader shows first and scales by. It does not reorder the recipe’s yields.

integer format: int64

<= 99

rating

integer format: int32

>= 1 <= 5

key

additional properties

any

Example

{
  "sources": [
    {
      "kind": "url"
    }
  ]
}

Headers

ETag

string

400

Bad Request

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

401

No valid session or API token (authentication-required), or the credential sent is invalid (invalid-credentials).

Media typeapplication/problem+json

object

code

required

string

detail

required

string

status

required

integer format: int64

title

required

string

type

required

string

key

additional properties

any

Example^generated

{
  "code": "example",
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

404

Not Found

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

409

Conflict

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

412

Precondition Failed

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

422

Unprocessable Entity

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

428

Precondition Required

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

500

Internal Server Error

Media typeapplication/problem+json

object

code

Stable application error code; clients may also use the problem type suffix.

string

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

key

additional properties

any

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

params

Structured context for the stable error code.

object

key

additional properties

any

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

violations

Array<object>

object

code

required

string

location

required

string

params

object

key

additional properties

any

key

additional properties

any

Example

{
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}