# AnnotationsApi.create()

```ts
create(pageIndex: number, annotation: NewAnnotation, options?: SignedDocumentOptions): Promise<string>
```

Adds one. A text mark (`highlight`, `underline`, `squiggly`, `strikeout`) covers `quads` (omitted or empty: its `rect`, which becomes their bounds); a `line` needs `line`, an `ink` needs `inkList`, a `polygon` needs `vertices` (three or more corners), a `polyline` too (two or more). A square, circle, line, drawing, polygon or polyline is written as its tool writes it — the same properties and appearance, so `lineEndings: { end: 'openArrow' }` is the Arrow tool's arrow: a square's or circle's `rect` is the box given; a line's, drawing's, polygon's or polyline's is worked out from its geometry, and the one given is not used.

A shape with no `color` is drawn in `#18181B`, the default palette's first color; `strokeWidth` is up to 14 400 points, one point when omitted or `null`, and `0` gives a square, circle or polygon no outline (a line, drawing or polyline is drawn at one point for `0`); `lineEndings` default to `'none'` and are ignored on anything but a line; `borderStyle` is `solid` when omitted, `dashed` or `dotted` is a pattern sized to the stroke, and `cloudy` goes round a square, circle or polygon only (an open shape asked for it is drawn solid). An `id` of your own is written as its name — saved in the file for every reader, so no secrets — and must be one no annotation in the document carries, at most 256 characters, no control characters; omitted, it gets a UUID. `flags` (a `Partial<AnnotationFlags>`: a flag left out is off, and it prints unless `noPrint`) are written as given. A link goes to `uri` — `http:`, `https:`, `mailto:` or `tel:`, a bare address gets `https://`, stored percent-encoded — or to `targetPage`. Needs the `annotations` feature.

- Kind: method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `pageIndex` | `number` | Zero-based page index. |
| `annotation` | `NewAnnotation` | `type` (one of `highlight`, `underline`, `squiggly`, `strikeout`, `note`, `link`, `square`, `circle`, `line`, `ink`, `polygon`, `polyline`) and `rect` are required; `contents`, `author`, `color`, `opacity`, `fillColor`, `quads`, `line`, `inkList`, `vertices`, `strokeWidth`, `lineEndings`, `borderStyle`, `uri`, `targetPage`, `id`, `flags`, `created` and `modified` are optional. |
| `options?` | `SignedDocumentOptions` | `{ invalidateSignatures? }`. |

Returns `Promise<string>`: The new annotation's id.

Throws:

- `INVALID_ARGUMENT` — a stamp, a free text, a `type` it does not make (the message names the ones it does: `'rectangle'` is `'square'`), a missing line, strokes or corners, a shape point that is not a number or lies past ±14 400 points, a color string the API does not take, an `opacity` outside 0–1, a stroke width outside 0 to 14 400, an end cap not in `LineEnding`, a border style not in `BorderStyle`, another link scheme, a `targetPage` that is not a page of the document, a `pageIndex` that is not a page of the document, an `id` that is empty, taken, longer than 256 characters, holds a control character or is of the `obj:…` form the SDK derives, a web link whose `uri` is `''`, or text-mark quads with a coordinate that is not a number or lies past ±14 400 points, or that run along more than 1 440 000 points of line in all.
- `PAGE_ERROR` — the annotation could not be added.
- `FEATURE_NOT_LICENSED` — the license lacks `annotations`.
- `DOCUMENT_CLOSED` — the document has been closed.
- `INVALID_STATE` — a certified document whose certification forbids it, unless `options.invalidateSignatures`; or a progressive document still downloading.

```ts
const id = await doc.annotations.create(0, {
  type: 'line',
  rect: { x: 0, y: 0, width: 0, height: 0 }, // worked out from the geometry
  line: { start: { x: 72, y: 600 }, end: { x: 300, y: 600 } },
  lineEndings: { end: 'openArrow' }, // the Arrow tool's arrow
  color: '#D92D20',
});
```

Part of [AnnotationsApi](https://kernstra.com/docs/web-sdk/api/doc-annotations) in the Kernstra Web SDK 1.0.0 API reference.

Web page: https://kernstra.com/docs/web-sdk/api/doc-annotations/create