Save what you extracted from a document

documents.extract.save

POST/api/v1/households/{household_id}/commands/documents.extract.save

Command
Rigel runs it
Applies offline

Keeps structured information you worked out from a document (a policy's number and dates, a statement's lines), so the next question doesn't need the file read again. Replaces an earlier extract of the same kind on the document. Give data as JSON and text as the same information in plain lines for search. Optionally also sets the document's summary. The extract is marked stale when the document's text later changes.

Parameters#

Save what you extracted from a document: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`Idempotency-Key`headerstringoptional	The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Save what you extracted from a document: request body fields
Field	Description
`document_id`stringrequired	A document ID, such as doc_01JC0000000000000000000000.
`kind`stringrequired	What was extracted, in snake case: insurance_policy, bank_statement, warranty. Reuse an existing kind when it fits. 1 to 60 characterspattern ^[a-z][a-z0-9_]*$
`data`anyrequired	The extracted fields and rows, as any JSON value, up to 256 KB. Its shape is yours to choose; reuse the shape of earlier extracts of the same kind.
`text`stringrequired	The same information as plain lines ("Policy number: H-2231-88"), 1–100,000 characters. 1 to 100,000 characters
`summary`stringoptional	Also set the document's summary. at most 5,000 characters

Response#

200 The command was applied.

Save what you extracted from a document: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`result.extract_id`stringrequired	The extract, new or replaced.
`version`integerrequired	The household version after the command.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Save what you extracted from a document: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`document_not_found`	A document that is gone.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	`idempotency_key_reused`	The Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

A new extract, stored as canonical JSON

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    kind: "insurance_policy",
    data: {
      policy: "H-2231",
      coverage: {
        dwelling: 300000,
      },
    },
    text: "Policy number: H-2231",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0AE20D05ECFPV5RG6

{
  "result": {
    "extract_id": "dcx_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

Replacing an earlier extract of the same kind

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    kind: "insurance_policy",
    data: {
      policy: "H-2231",
      coverage: {
        dwelling: 300000,
      },
    },
    text: "Policy number: H-2231",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0S37M3HDCWWREYR4J

{
  "result": {
    "extract_id": "dcx_01JC0000000000000000000001"
  },
  "version": 1
}

Another kind is a separate extract, and the summary is set

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231",
  "summary": "Home policy H-2231"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    kind: "insurance_policy",
    data: {
      policy: "H-2231",
      coverage: {
        dwelling: 300000,
      },
    },
    text: "Policy number: H-2231",
    summary: "Home policy H-2231",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231",
  "summary": "Home policy H-2231"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0CTCTPRPVYVJFR3JS

{
  "result": {
    "extract_id": "dcx_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

An extract of a file

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC000000000000000000000F",
  "kind": "insurance_policy",
  "data": [
    1,
    2
  ],
  "text": "Policy number: H-2231"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC000000000000000000000F",
    kind: "insurance_policy",
    data: [
      1,
      2,
    ],
    text: "Policy number: H-2231",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC000000000000000000000F",
  "kind": "insurance_policy",
  "data": [
    1,
    2
  ],
  "text": "Policy number: H-2231"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R07HZTZPAS940T38PM

{
  "result": {
    "extract_id": "dcx_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A document that is gone

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    document_id: "doc_01JC0000000000000000000001",
    kind: "insurance_policy",
    data: {
      policy: "H-2231",
      coverage: {
        dwelling: 300000,
      },
    },
    text: "Policy number: H-2231",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.extract.save HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "document_id": "doc_01JC0000000000000000000001",
  "kind": "insurance_policy",
  "data": {
    "policy": "H-2231",
    "coverage": {
      "dwelling": 300000
    }
  },
  "text": "Policy number: H-2231"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0MSCYZ1EM7CDZ7NAP

{
  "error": {
    "code": "document_not_found",
    "message": "That document isn't there any more. No changes were applied.",
    "details": {
      "document_id": "doc_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0MSCYZ1EM7CDZ7NAP"
  }
}

For Rigel#

Rigel's tool for this command is documents_extract_save. Rigel runs this on its own, then says what it did. The agent guide has the rest.