The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: 3. HTTP routes
description: Trigger the function over HTTP and render documents as web pages.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import { CardTitle } from "/snippets/card-title.mdx"
## Overview
The same handler can also answer HTTP requests. We'll add two routes:
- a **POST** endpoint the UI calls to generate a document, and
- a public **GET** endpoint that renders a document as a printable web page.
Both use `httpRouteTriggerSettings`. App routes are addressed with an `/s/` path; on local
and self-hosted instances, that path is served by your Twenty server
(e.g. `http://localhost:2020/s/documents/generate`). On Twenty Cloud, `RestApiClient`
resolves the path through the workspace's functions domain.
## POST route — generate on demand
This reuses `generateDocumentHandler`, so there's no logic to repeat — just a thin
adapter that reads the request body.
```ts filename="src/logic-functions/generate-document-route.ts"
import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
import { Response } from 'twenty-sdk/logic-function';
import { generateDocumentHandler } from 'src/logic-functions/handlers/generate-document-handler';
const handler = async (event: RoutePayload): Promise<Response> => {
const body = event.body as Record<string, unknown> | null;
const result = await generateDocumentHandler({
templateId: (body?.templateId as string) ?? '',
recordId: (body?.recordId as string) ?? '',
});
// Map the handler's failure reason onto a real HTTP status (400/404/500)
// instead of always returning 200.
return new Response(JSON.stringify(result), {
status: result.success ? 200 : (result.status ?? 400),
headers: { 'Content-Type': 'application/json' },
});
};
export default defineLogicFunction({
universalIdentifier: GENERATE_DOCUMENT_ROUTE_UNIVERSAL_IDENTIFIER,
name: 'generate-document-route',
timeoutSeconds: 30,
handler,
httpRouteTriggerSettings: {
path: '/documents/generate',
httpMethod: 'POST',
isAuthRequired: true,
},
});
```
The shared handler returns a suggested `status` on failure, so the route can
answer with a proper `4xx`/`5xx` code. `isAuthRequired: true` means the caller
must present a valid token — the front component in the next chapter passes the
user's access token automatically.
## GET route — render as a web page
To return HTML instead of JSON, wrap the body in a `Response` with a
`Content-Type` header. This route is public (`isAuthRequired: false`) so a
generated document can be shared as a link.
```ts filename="src/logic-functions/view-document.ts"
import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
import { Response } from 'twenty-sdk/logic-function';
import { CoreApiClient } from 'twenty-client-sdk/core';
import { documentHtmlPage } from 'src/utils/render-document';
const htmlResponse = (html: string, status = 200): Response =>
new Response(html, {
status,
headers: { 'Content-Type': 'text/html; charset=utf-8' },
});
const handler = async (event: RoutePayload): Promise<Response> => {
const documentId = event.queryStringParameters?.id;
if (!documentId) {
return htmlResponse(
documentHtmlPage('Missing document id', 'Provide ?id=<documentId>.'),
400,
);
}
// Filtered list query so an unknown id renders a clean 404 page instead of throwing.
const { documents } = await new CoreApiClient().query({
documents: {
__args: { filter: { id: { eq: documentId } }, first: 1 },
edges: { node: { id: true, name: true, content: true } },
},
});
const document = documents?.edges?.[0]?.node;
if (!document?.id) {
return htmlResponse(
documentHtmlPage(
'Document not found',
`No document with id ${documentId}.`,
),
404,
);
}
return htmlResponse(
documentHtmlPage(document.name ?? 'Document', document.content ?? ''),
);
};
export default defineLogicFunction({
universalIdentifier: VIEW_DOCUMENT_ROUTE_UNIVERSAL_IDENTIFIER,
name: 'view-document',
timeoutSeconds: 15,
handler,
httpRouteTriggerSettings: {
path: '/documents/view',
httpMethod: 'GET',
isAuthRequired: false,
},
});
```
`documentHtmlPage` renders the Markdown body to HTML (with [marked](https://marked.js.org/),
sanitized) and drops it into a clean, printable page that shows just the template
content — the same look as the PDF and the in-app preview.
[See the helper](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/document-generator/src/utils/render-document.ts).
## Try it
With a template and a Person in your workspace, call the route (grab a token from
**Settings → Developers → API**):
```bash filename="Terminal"
curl -X POST http://localhost:2020/s/documents/generate \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"templateId":"<templateId>","recordId":"<personId>"}'
# → {"success":true,"documentId":"...","content":"Dear Jeffery Griffin, ..."}
```
Open the returned document in your browser:
```
http://localhost:2020/s/documents/view?id=<documentId>
```
<Frame caption="The public GET route renders the document as a printable page.">
<img
src="/images/docs/developers/extends/apps/document-generator/07-rendered-document.png"
alt="A rendered document web page"
/>
</Frame>
<Tip>
You can also stream a function's logs while testing with `twenty app logs`, or
invoke it directly with `twenty app exec`.
</Tip>
**After this step:** the app can generate documents over HTTP and serve them as
web pages. Now let's make it usable without `curl`.
<CardGroup cols={2} className="documentation-card-group">
<Card href="/developers/extend/apps/tutorials/document-generator/building-the-ui" img="/images/user-guide/halftone/card-page-tutorial-ui.svg">
<CardTitle>Next: building the UI →</CardTitle>
Views, navigation, a command, and a front component.
</Card>
</CardGroup>
<PageBanner illustration="card-page-tutorial-http" />