# Documents API

Source: https://frameleaf.app/docs/api/reference/documents/

Use your own server and its scoped API keys.

## Search documents

GET /api/documents

List the signed-in account’s photos that show recognized text, newest first, optionally matching text read from them or the owner’s corrections.

```json
{
  "description": "List the signed-in account’s photos that show recognized text, newest first, optionally matching text read from them or the owner’s corrections.",
  "operationId": "searchDocuments",
  "parameters": [
    {
      "name": "page",
      "required": false,
      "in": "query",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "default": 1,
        "type": "integer"
      }
    },
    {
      "name": "query",
      "required": false,
      "in": "query",
      "description": "Text to find in recognized text and in the owner’s corrections",
      "schema": {
        "maxLength": 200,
        "type": "string"
      }
    },
    {
      "name": "size",
      "required": false,
      "in": "query",
      "schema": {
        "minimum": 1,
        "maximum": 250,
        "default": 100,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DocumentSearchResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Search documents",
  "tags": [
    "Documents"
  ],
  "x-frameleaf-permission": "asset.read"
}
```

## Retrieve a document

GET /api/documents/{id}

Retrieve the text read from a photo with the owner’s corrections applied, where each line is in the photo, and, for the owner, the values suggested from it.

```json
{
  "description": "Retrieve the text read from a photo with the owner’s corrections applied, where each line is in the photo, and, for the owner, the values suggested from it.",
  "operationId": "getDocument",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DocumentResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve a document",
  "tags": [
    "Documents"
  ],
  "x-frameleaf-permission": "asset.read"
}
```

## Clear a document field decision

DELETE /api/documents/{id}/fields/{field}

Remove the owner’s decision about a field, so the text’s suggestion shows again.

```json
{
  "description": "Remove the owner’s decision about a field, so the text’s suggestion shows again.",
  "operationId": "deleteDocumentField",
  "parameters": [
    {
      "name": "field",
      "required": true,
      "in": "path",
      "schema": {
        "$ref": "#/components/schemas/DocumentField"
      }
    },
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "revision",
      "required": true,
      "in": "query",
      "description": "Revision of the decision being removed",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DocumentResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Clear a document field decision",
  "tags": [
    "Documents"
  ],
  "x-frameleaf-permission": "asset.update"
}
```

## Decide a document field

PUT /api/documents/{id}/fields/{field}

Confirm, correct or dismiss a value suggested from the text of a photo.

```json
{
  "description": "Confirm, correct or dismiss a value suggested from the text of a photo.",
  "operationId": "updateDocumentField",
  "parameters": [
    {
      "name": "field",
      "required": true,
      "in": "path",
      "schema": {
        "$ref": "#/components/schemas/DocumentField"
      }
    },
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DocumentFieldEditDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DocumentResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Decide a document field",
  "tags": [
    "Documents"
  ],
  "x-frameleaf-permission": "asset.update"
}
```

## Correct or dismiss a line of text

PUT /api/documents/{id}/lines

Record the owner’s correction or dismissal of one recognized line. The recognized text itself is kept unchanged.

```json
{
  "description": "Record the owner’s correction or dismissal of one recognized line. The recognized text itself is kept unchanged.",
  "operationId": "updateDocumentLine",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DocumentLineEditDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DocumentResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Correct or dismiss a line of text",
  "tags": [
    "Documents"
  ],
  "x-frameleaf-permission": "asset.update"
}
```

## Restore a line of text

DELETE /api/documents/{id}/lines/{editId}

Remove the owner’s correction or dismissal of a line, so it reads as recognized again.

```json
{
  "description": "Remove the owner’s correction or dismissal of a line, so it reads as recognized again.",
  "operationId": "deleteDocumentLine",
  "parameters": [
    {
      "name": "editId",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "revision",
      "required": true,
      "in": "query",
      "description": "Revision of the decision being removed",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DocumentResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Restore a line of text",
  "tags": [
    "Documents"
  ],
  "x-frameleaf-permission": "asset.update"
}
```