Skip to content
Rigel docs
Open Rigel

Make a document from an uploaded file

documents.document.add_file

POST/api/v1/households/{household_id}/commands/documents.document.add_file

  • Command
  • Rigel runs it
  • Applies offline

Files an uploaded file (a PDF, a photo, anything) as a document. Upload the file first; this takes its file_id. The title defaults to the file's name without its extension. The document's text starts empty: a PDF's text layer is added by the web app, and anything else is read when someone needs it. Pass links to keep the file with a record (a manual with the furnace). Refused with file_not_found, folder_not_found or record_not_found.

Parameters#

Make a document from an uploaded file: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

Idempotency-Keyheaderstringoptional

The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Make a document from an uploaded file: request body fields
FieldDescription
file_idstringrequired

The uploaded file.

titlestringoptional

The title; defaults to the file's name without its extension.

1 to 300 characters
folder_idstringoptional

The folder to file it in; leave out to leave it unfiled.

linksarray of objectsoptional

Records to link the new document to, such as the furnace it is the manual for. A record listed twice is linked once, with the last note.

at most 50 items
links[].record_idstringrequired

The ID of any record in the household, such as tsk_01JC0000000000000000000000.

1 to 100 characters
links[].notestringoptional

Why they are linked, when it isn't obvious: "manual", "quote", "warranty".

at most 200 characters
appone of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenanceoptional

The app this file is being kept for, recorded as the document's source.

Response#

200 The command was applied.

Make a document from an uploaded file: response fields
FieldDescription
resultobjectrequired

What the command returned, such as the IDs it created.

result.document_idstringrequired

The new document.

versionintegerrequired

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.

Make a document from an uploaded file: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404file_not_foundA file that is gone.
404folder_not_foundA folder that is gone.
404record_not_foundA record that is gone.
404not_foundThe household doesn't exist, or you aren't a member of it.
409idempotency_key_reusedThe 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.

The title defaults to the file name without its extension

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0X1EXYE8E3N59200Z

{
  "result": {
    "document_id": "doc_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A given title, folder and app

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001",
  "title": "Furnace manual",
  "folder_id": "fld_01JC0000000000000000000001",
  "app": "maintenance"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
    title: "Furnace manual",
    folder_id: "fld_01JC0000000000000000000001",
    app: "maintenance",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001",
  "title": "Furnace manual",
  "folder_id": "fld_01JC0000000000000000000001",
  "app": "maintenance"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0MAMD23EVCYXVFCAT

{
  "result": {
    "document_id": "doc_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A name that is only an extension keeps the whole name

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0TB8NNCWMV61409PK

{
  "result": {
    "document_id": "doc_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A name with no extension

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0JP1V9SNGFG53KZQJ

{
  "result": {
    "document_id": "doc_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

Linked to a record

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001",
  "links": [
    {
      "record_id": "per_01JC0000000000000000000001",
      "note": "card"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
    links: [
      {
        record_id: "per_01JC0000000000000000000001",
        note: "card",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001",
  "links": [
    {
      "record_id": "per_01JC0000000000000000000001",
      "note": "card"
    }
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0VWJEVKERVST5V4ZA

{
  "result": {
    "document_id": "doc_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A file that is gone

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0V391HX3MFMEX7ETR

{
  "error": {
    "code": "file_not_found",
    "message": "That file isn't there any more. No changes were applied.",
    "details": {
      "file_id": "fil_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0V391HX3MFMEX7ETR"
  }
}

A folder that is gone

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001",
  "folder_id": "fld_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
    folder_id: "fld_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001",
  "folder_id": "fld_01JC0000000000000000000001"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0421N4J0MEY2T66N2

{
  "error": {
    "code": "folder_not_found",
    "message": "That folder isn't there any more. No changes were applied.",
    "details": {
      "folder_id": "fld_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0421N4J0MEY2T66N2"
  }
}

A record that is gone

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "file_id": "fil_01JC0000000000000000000001",
  "links": [
    {
      "record_id": "per_01JC0000000000000000000001"
    }
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01JC0000000000000000000001",
    links: [
      {
        record_id: "per_01JC0000000000000000000001",
      },
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "file_id": "fil_01JC0000000000000000000001",
  "links": [
    {
      "record_id": "per_01JC0000000000000000000001"
    }
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0NG9Z5BXH8MX3ENK8

{
  "error": {
    "code": "record_not_found",
    "message": "There is no record with that ID, so it can't be linked. No changes were applied.",
    "details": {
      "record_id": "per_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0NG9Z5BXH8MX3ENK8"
  }
}

File an uploaded photo as a document

Upload the file first. Its text starts empty and is read later.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.add_file' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CTAC67ZSN952JW59Y97Q' \
  -d '{
  "file_id": "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
  "title": "Pantry middle shelf"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.add_file", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CTAC67ZSN952JW59Y97Q",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    file_id: "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
    title: "Pantry middle shelf",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/documents.document.add_file HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CTAC67ZSN952JW59Y97Q

{
  "file_id": "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
  "title": "Pantry middle shelf"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTAC7FNGFVP65CJ1XGQS

{
  "result": {
    "document_id": "doc_01M6V9CTAC5Y4Z9FTG59AEDPTH"
  },
  "version": 303
}

For Rigel#

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

Rigel is in early access, and sign-up is by invitation. Open Rigel