From eb3b3b18ce7b42af6a6acfe7be19066bebbfe72d Mon Sep 17 00:00:00 2001 From: David Nguyen Date: Wed, 28 Jan 2026 14:09:13 +1100 Subject: [PATCH] chore: add v1 deprecated docs (#2423) --- .../pages/developers/public-api/index.mdx | 13 +++++- packages/api/v1/contract.ts | 46 ++++++++++++++++--- packages/api/v1/openapi.ts | 3 +- 3 files changed, 53 insertions(+), 9 deletions(-) diff --git a/apps/documentation/pages/developers/public-api/index.mdx b/apps/documentation/pages/developers/public-api/index.mdx index f589c6c0f..1c844c394 100644 --- a/apps/documentation/pages/developers/public-api/index.mdx +++ b/apps/documentation/pages/developers/public-api/index.mdx @@ -31,9 +31,18 @@ Our new API V2 supports the following typed SDKs: ## API V1 - Deprecated -Check out the [API V1 documentation](https://app.documenso.com/api/v1/openapi) for details about the API endpoints, request parameters, response formats, and authentication methods. + + API V1 is deprecated. +
+ The V1 API will continue to be supported for the foreseeable future, but it is limited to + Legacy Documents (Documents created using the old non-envelope editor). -📖 [Documentation](https://documen.so/api-v2-docs) + Important: To work with the new Envelope document system, you + must use the + V2 API. + + +Check out the [API V1 documentation](https://app.documenso.com/api/v1/openapi) for details about the API endpoints, request parameters, response formats, and authentication methods. ## Availability diff --git a/packages/api/v1/contract.ts b/packages/api/v1/contract.ts index 50f096498..172c9833f 100644 --- a/packages/api/v1/contract.ts +++ b/packages/api/v1/contract.ts @@ -43,6 +43,9 @@ import { const c = initContract(); +const deprecatedDescription = + 'This endpoint is deprecated, but will continue to be supported. For more details, see https://docs.documenso.com/developers/public-api.'; + export const ApiContractV1 = c.router( { getDocuments: { @@ -55,6 +58,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Get all documents', + deprecated: true, + description: deprecatedDescription, }, getDocument: { @@ -66,6 +71,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Get a single document', + deprecated: true, + description: deprecatedDescription, }, downloadSignedDocument: { @@ -78,6 +85,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Download a signed document when the storage transport is S3', + deprecated: true, + description: deprecatedDescription, }, createDocument: { @@ -90,6 +99,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Upload a new document and get a presigned URL', + deprecated: true, + description: deprecatedDescription, }, createTemplate: { @@ -102,6 +113,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Create a new template and get a presigned URL', + deprecated: true, + description: deprecatedDescription, }, deleteTemplate: { @@ -114,6 +127,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Delete a template', + deprecated: true, + description: deprecatedDescription, }, getTemplate: { @@ -125,6 +140,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Get a single template', + deprecated: true, + description: deprecatedDescription, }, getTemplates: { @@ -137,6 +154,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Get all templates', + deprecated: true, + description: deprecatedDescription, }, createDocumentFromTemplate: { @@ -150,7 +169,7 @@ export const ApiContractV1 = c.router( }, summary: 'Create a new document from an existing template', deprecated: true, - description: `This has been deprecated in favour of "/api/v1/templates/:templateId/generate-document". You may face unpredictable behavior using this endpoint as it is no longer maintained.`, + description: `${deprecatedDescription} \n\nIf you must use the V1 API, use "/api/v1/templates/:templateId/generate-document" instead.`, }, generateDocumentFromTemplate: { @@ -165,8 +184,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Create a new document from an existing template', - description: - 'Create a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.', + deprecated: true, + description: `${deprecatedDescription} \n\nCreate a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.`, }, sendDocument: { @@ -181,9 +200,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Send a document for signing', - // I'm aware this should be in the variable itself, which it is, however it's difficult for users to find in our current UI. - description: - 'Notes\n\n`sendEmail` - Whether to send an email to the recipients asking them to action the document. If you disable this, you will need to manually distribute the document to the recipients using the generated signing links. Defaults to true', + deprecated: true, + description: `${deprecatedDescription} \n\nNotes\n\nsendEmail - Whether to send an email to the recipients asking them to action the document. If you disable this, you will need to manually distribute the document to the recipients using the generated signing links. Defaults to true`, }, resendDocument: { @@ -198,6 +216,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Re-send a document for signing', + deprecated: true, + description: deprecatedDescription, }, deleteDocument: { @@ -210,6 +230,8 @@ export const ApiContractV1 = c.router( 404: ZUnsuccessfulResponseSchema, }, summary: 'Delete a document', + deprecated: true, + description: deprecatedDescription, }, createRecipient: { @@ -224,6 +246,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Create a recipient for a document', + deprecated: true, + description: deprecatedDescription, }, updateRecipient: { @@ -238,6 +262,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Update a recipient for a document', + deprecated: true, + description: deprecatedDescription, }, deleteRecipient: { @@ -252,6 +278,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Delete a recipient from a document', + deprecated: true, + description: deprecatedDescription, }, createField: { @@ -266,6 +294,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Create a field for a document', + deprecated: true, + description: deprecatedDescription, }, updateField: { @@ -280,6 +310,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Update a field for a document', + deprecated: true, + description: deprecatedDescription, }, deleteField: { @@ -294,6 +326,8 @@ export const ApiContractV1 = c.router( 500: ZUnsuccessfulResponseSchema, }, summary: 'Delete a field from a document', + deprecated: true, + description: deprecatedDescription, }, }, { diff --git a/packages/api/v1/openapi.ts b/packages/api/v1/openapi.ts index 293395b18..43cecb2ac 100644 --- a/packages/api/v1/openapi.ts +++ b/packages/api/v1/openapi.ts @@ -11,7 +11,8 @@ export const OpenAPIV1 = Object.assign( info: { title: 'Documenso API', version: '1.0.0', - description: 'The Documenso API for retrieving, creating, updating and deleting documents.', + description: + 'API V1 is deprecated, but will continue to be supported. For more details, see https://docs.documenso.com/developers/public-api. \n\nThe Documenso API for retrieving, creating, updating and deleting documents.', }, servers: [ {