--- title: "putSchemaAnnotation" description: "Create or replace a schema annotation" canonical: "https://pgbeam.com/docs/ts-sdk/schemaannotations/putSchemaAnnotation" last-updated: "2026-09-09T11:37:53.000Z" --- # putSchemaAnnotation > Create or replace a schema annotation URL: https://pgbeam.com/docs/ts-sdk/schemaannotations/putSchemaAnnotation Attaches an operator-written description to a table (omit column\_name) or a column. Keyed by (schema\_name, table\_name, column\_name); an existing annotation with the same key is replaced. ## Usage ## Parameters Parameter Type Required Description pathParams.project\_id `string` Yes Unique project identifier (prefixed, e.g. prj\_xxx). body.schema\_name `string` No Optional schema. Null or empty matches the unqualified form. body.table\_name `string` Yes Relation (table or view) the annotation describes. body.column\_name `string` No Optional column. Null describes the table itself. body.description `string` Yes The operator-written description text. ## Response `Promise`: the created or updated annotation. ## Example ## Errors Status Description 400 The request was rejected. `code` is `INVALID_INPUT`, and `errors` names the offending fields when the failure was a validation one. 401 Missing or invalid authentication. `code` is `UNAUTHORIZED`. 403 The caller is authenticated but not allowed to perform this operation. `code` is `FORBIDDEN` when the caller's role is insufficient, and `PLAN_LIMIT_REACHED` when the organization's plan is what stands in the way. The two are answered differently, so branch on the code rather than the status. 404 The resource does not exist, or the caller is not entitled to know that it does. `code` is `NOT_FOUND`. 413 The request body exceeds the 2 MB limit. `code` is `PAYLOAD_TOO_LARGE`. 415 The request body is not JSON, or carries a body without declaring a Content-Type. `code` is `UNSUPPORTED_MEDIA_TYPE`. 429 Rate limited. `code` is `RATE_LIMITED`. 500 The request failed for a reason on our side. `code` is `INTERNAL_ERROR`. Quote `request_id` when reporting it.