# Dev > ## Documentation Index --- # Source: https://dev.writer.com/AGENTS.md > ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # null # Developer documentation style guide This guide covers how to write and organize documentation for Writer's developer platform. It combines content strategy with style rules to create docs that get developers productive quickly. > \[!NOTE] > This guide is for developer documentation. Writer maintains a [general style guide](https://writer.styleguide.com/) for other marketing and product writing. ## Foundation * Follow [Google's developer documentation style guide](https://developers.google.com/style) as the base reference * When in doubt, defer to Google's guidelines unless explicitly overridden below * Check Vale rules and dictionaries for approved terminology and product names ## Content principles ### Core philosophy Documentation should get developers productive as quickly as possible. Every piece of content should either help them complete a task or understand why that task matters. Developers come to documentation to solve specific problems, like implementing a feature or debugging an issue. They scan for relevant information, jump between sections, and search for targeted solutions. They don't read docs cover-to-cover. Documentation should be organized to support this problem-solving behavior with clear headings, easy navigation, and solutions that are quick to find. ### Content strategy #### Start with outcomes, not features * Lead every document with what the developer will accomplish * Explain the business value or technical benefit upfront #### Show, don't just tell * Lead with working code examples, not conceptual explanations * Use realistic data and scenarios in examples * Demonstrate the "happy path" first, then cover edge cases #### Progressive complexity * Start with the smallest possible working example * Build complexity gradually in logical steps * Each section should build on knowledge from previous sections * Layer on configuration options and advanced features incrementally #### Focus on success paths * Document the most common, successful implementation patterns * Show working examples that developers can build on * Provide clear verification steps so developers know they're on track * Keep examples focused on core functionality rather than edge cases ### Content organization #### Task-oriented structure * Organize content around what developers need to do, not product features * Use action-oriented headings that describe outcomes ("Chat with an LLM" not "Chat completions") * Use descriptive headings that match how people search ("Fix authentication errors" not "Error handling") * Group related tasks together logically * Provide clear pathways between related tasks #### Front-load solutions * Put the most common answer or code example at the top of each section * Lead with "here's how to do X" before explaining background theory * Save conceptual explanations for later sections * Each heading should solve one specific problem #### Scannable structure * Keep sections short and focused on single problems * Use visual hierarchy with code blocks, bullet points, and bold text * Break up walls of text to support scanning behavior * Create quick reference sections for parameters, error codes, and common patterns #### Prose after headings (required) **Always include one or two prose sentences immediately after a heading before any structured content** (bulleted lists, code blocks, tables, etc.). Never jump directly from a heading to a list or code sample. Orient the reader to what the section contains and provide context. ❌ Bad (no prose after heading): ```markdown theme={null} ## Best practices - Do this - Do that ``` ✅ Good (prose after heading): ```markdown theme={null} ## Best practices Best practices include proper error handling, secure authentication, and efficient rate limiting. Follow these guidelines to ensure optimal performance and security. - Do this - Do that ``` #### Multiple entry points * Optimize headings for search discoverability * Cross-link between related content when someone might land on the wrong page * Provide multiple ways to find the same information * Structure content to support both search and browsing #### Content reuse and consistency * Use snippets for content that appears on multiple pages * Keep shared information in reusable components * Maintain consistency in explanations across different contexts * Update snippets in one place to propagate changes everywhere #### Minimize context switching * Keep related information on the same page when possible * Avoid forcing developers to jump between concept docs and API references * Include inline parameter descriptions next to code examples * Provide all necessary information to complete a task in one location #### Avoid time-sensitive language * Limit time references to changelog entries and deprecation warnings * Don't use "the new feature," "recently," "as of \[date]," or "latest version", which creates documentation debt and makes content feel outdated * Replace "As of November 2025, this feature is available..." with "This feature is available..." or "This feature provides..." * Replace "The new API endpoint..." with "The API endpoint..." or "This endpoint..." * Replace "Recently added support for..." with "Support for..." or "This includes support for..." ## Style rules ### Document structure requirements #### Opening pattern (required) Every documentation file must start with: * What the reader will learn (specific outcomes) * Why this matters (problem solved or benefit provided) **Example format:** ```markdown theme={null} This guide shows you how to [specific action]. After completing these steps, you can [concrete outcome]. ``` #### Closing pattern (required) Every documentation file must end with "Next steps" section containing: * Links to logical follow-up tutorials * Related features to explore * Advanced configuration options, if applicable ### Voice and language rules #### Always use * Active voice ("Configure the API" not "The API should be configured") * Direct address with "you" and "your" * Present tense for current features ("Add the code" not "You will add the code") * Sentence case for all headings * Direct, imperative instructions ("Install the SDK" not "You need to install the SDK") #### Never use * First person plural: "we," "us," "our" * Creates confusion about whether "we" means Writer or you and the reader * "Please" * Overly polite for technical documentation * Future tense with "will" for current features * Use present tense instead, which feels more immediate and actionable * Subjective qualifiers: "simple," "basic," "easy," "trivial," "straightforward," "just," "simply," "obviously" * Makes people feel inadequate if they struggle with the task * Marketing language: "powerful," "amazing," "revolutionary," "cutting-edge," "industry-leading," "seamlessly," "effortlessly," "instantly" * Sounds promotional rather than helpful * Banned corporate buzzwords: "leverage," "utilize," "optimize," "robust," "streamline," "synergy," "paradigm," "game-changer," "low-hanging fruit" * Vague and overused * Hyperbolic terms or marketing speak #### Word replacements: * "This simple API" → "This API" * "You need to install X" → "Install X" * "You need to configure Y" → "Configure Y" * "Our powerful system" → "The system" * "Just add the code" → "Add the code" * "We recommend" → "Use" or "Consider using" * "This tutorial will show you" → "This tutorial demonstrates" * "You will be able to" → "You can" * "Please install" → "Install" * "Please configure" → "Configure" * "Utilize" → "Use" * "Leverage the API" → "Use the API" * "Click the button" → "Select the button" * "Since you need to..." → "Because you need to..." ### Content guidelines #### Code examples: * **Always provide complete, independently executable examples** - code must be runnable as-is without requiring additional setup * Always provide complete, working examples with realistic data (not foo/bar placeholders) * Lead with working code examples, not theory or lengthy explanations * Include necessary imports and dependencies * Use realistic variable names and values that match actual use cases * Add comments for non-obvious code * Test all examples in multiple environments before publishing * **Use `` component for multi-language examples** (cURL, Python, JavaScript) * Show multiple language examples when relevant (Python, JavaScript, curl) * Focus on successful implementation patterns and happy paths * Keep related code and explanations on the same page to prevent context switching * Use snippets for code that appears on multiple pages to maintain consistency * **Always include one or two prose sentences after headings and before code samples** to orient the reader - never jump directly from a heading to code ##### SDK initialization pattern (required for API/SDK examples) For all API and SDK examples (not Agent Builder), always include the complete initialization pattern. Code samples must be independently executable. **Python initialization:** ```python theme={null} from writerai import Writer # Initialize the Writer client. If you don't pass the `api_key` parameter, # the client looks for the `WRITER_API_KEY` environment variable. client = Writer() ``` **JavaScript initialization:** ```javascript theme={null} import { Writer } from "writer-sdk"; // Initialize the Writer client. If you don't pass the `api_key` parameter, // the client looks for the `WRITER_API_KEY` environment variable. const client = new Writer(); ``` **Note:** Agent Builder examples do not follow this pattern as they use the Agent Builder framework, not the SDK directly. ##### CodeGroup component usage Always use `` for code samples, especially for cURL, Python, and JavaScript examples. This is not necessary for standalone JSON examples or Agent Builder content (which is Python-only), but is required for: * API endpoint examples (include cURL, Python, and JavaScript) * SDK usage examples (include Python and JavaScript where applicable) * Any code that shows implementation across multiple languages **Example:** ````mdx theme={null} ```bash cURL curl -X POST https://api.writer.com/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "palmyra-x-004", "messages": [{"role": "user", "content": "Hello!"}] }' ``` ```python Python from writerai import Writer # Initialize the Writer client. If you don't pass the `api_key` parameter, # the client looks for the `WRITER_API_KEY` environment variable. client = Writer() response = client.chat.chat( model="palmyra-x-004", messages=[{"role": "user", "content": "Hello!"}] ) ``` ```javascript JavaScript import { Writer } from "writer-sdk"; // Initialize the Writer client. If you don't pass the `api_key` parameter, // the client looks for the `WRITER_API_KEY` environment variable. const client = new Writer(); const response = await client.chat.chat({ model: "palmyra-x-004", messages: [{ role: "user", content: "Hello!" }] }); ``` ```` ##### Mintlify component imports **Important:** Built-in Mintlify components like ``, ``, ``, ``, ``, ``, etc. do NOT need to be imported. They are available by default in all MDX files. **Only snippets need to be imported.** For example: ```mdx theme={null} import feedback from '/snippets/agent-builder-feedback.mdx'; ``` #### Alt text guidelines for images * Alt text provides a concise description that replaces the image when it's not visible * Alt text should consider the context of the image, not just its content * The goal: replacing every image with its alt text should not change the page's meaning ##### When to use alt text * **Informative images**: Images that convey information not present in surrounding text * **Functional images**: Images that serve as interactive elements (buttons, links) * **Complex images**: Charts, diagrams, or screenshots that need description ##### When to use empty alt text You can leave the alt text empty `![](/images/image.png)` in the following cases, so screen readers skip the image: * **Decorative images**: Images that exist only for visual appeal * **Redundant images**: Images whose information is already expressed in surrounding text * **UI screenshots**: Screenshots that exist just for visual reference * **UI icons**: Interface icons that are decorative or have text labels * **Visual aids**: Images that support information already present in text ##### Alt text writing guidelines * **Length**: Keep alt text under 155 characters * **Content**: Don't include "Image of" or "Photo of" phrases * **Punctuation**: Include punctuation for natural speech pauses * **Format**: Use full sentences or noun phrases * **Capitalization**: Avoid all-caps (screen readers may read each letter individually) * **Context**: Consider the image's purpose in the page, not just visual content * **Consistency**: Use consistent alt text for repeated images (controls, status indicators, icons) ##### Examples of good alt text * `![Architecture of an app that's built with Apps Script](/images/architecture.png)` * `![A card message](/images/card-message.png)` * `![User interface showing the login form with username and password fields](/images/login-form.png)` * `![Flowchart showing the authentication process from login to dashboard](/images/flowchart.png)` ##### Examples of when to use empty alt text * `![](/images/icon.png)` for decorative icons that have text labels * `![](/images/screenshot.png)` for UI screenshots that are explained in surrounding text * `![](/images/divider.png)` for visual dividers or decorative elements #### API documentation: * Start with what the endpoint does * List required parameters before optional ones * Include realistic request/response examples * Document error conditions and responses #### Tutorials: * Use numbered steps for procedures * Include verification steps ("You should see...") * Provide troubleshooting for common issues * End with clear next steps ### Formatting rules #### Numbers and punctuation: * Always use Oxford comma in lists * Spell out numbers 0-9, use numerals for 10+ unless it would be mixing numerals and words (ex: "there are 2 people and 15 dogs" is correct so that the numerals are not mixed with words) * Spell out numbers that start sentences * No periods in acronyms (UK not U.K.) * Use "generative AI" not "GenAI" or "gen AI" #### Headings: * Use sentence case for all headings: "Configure authentication" not "Configure Authentication" * Only capitalize the first word and proper nouns * Use action-oriented headings with imperative verbs that describe what the user will do * Be specific and descriptive about what the user will accomplish **Action-oriented heading patterns:** Always start headings with imperative verbs. Headings should tell users what they will do, not describe what exists. **Common transformations:** * ❌ "Key differences" → ✅ "Compare the APIs" * ❌ "Parameter mapping" → ✅ "Map your parameters" * ❌ "Accessing data" → ✅ "Access your data" * ❌ "Migration steps" → ✅ "Migrate your code" * ❌ "Next steps" → ✅ "Explore related features" * ❌ "Prerequisites" → ✅ "Prepare your environment" * ❌ "Configuration" → ✅ "Configure the settings" * ❌ "Installation" → ✅ "Install the SDK" * ❌ "Overview" → ✅ "Understand the basics" or "Learn about \[feature]" * ❌ "Authentication" → ✅ "Authenticate your requests" * ❌ "Error handling" → ✅ "Handle errors" * ❌ "Best practices" → ✅ "Follow best practices" or "Optimize your implementation" **Examples of correct sentence case with action verbs:** * ✅ "Set up your development environment" * ✅ "Send your first message" * ✅ "Stream responses in real-time" * ✅ "Configure authentication" * ✅ "Access translation metadata" * ✅ "Map your parameters" * ❌ "Set Up Your Development Environment" * ❌ "Chat Completions" * ❌ "API Reference" * ❌ "Key differences" * ❌ "Prerequisites" **Avoid these patterns:** * Gerunds as headings: "Configuring", "Installing", "Setting up" * Noun phrases: "Configuration", "Installation", "Overview", "Introduction" * Questions: "How do I configure X?" (just use the imperative: "Configure X") * Passive constructions: "Getting started" #### Links: * Use descriptive link text, never "click here", "read more", or "this link". "Learn more about authentication methods" is good, but "click here for documentation" is not. * Provide context for external links * Ensure all links are current and accessible * Run `mintlify broken-links` to check for broken links before publishing ## Example quality standards ### Realistic and tested examples * Use actual product data and realistic scenarios * Test all code examples in multiple environments * Show examples in multiple programming languages (Python, JavaScript) if available ### Complete and runnable code * Provide full working examples, not snippets that require guessing * Include all necessary imports, dependencies, and setup steps * Show the complete request/response cycle * Include error handling in examples when appropriate ### Contextual examples * Match examples to the specific use case being documented * Use variable names and data that reflect real-world usage * Show examples that developers can easily adapt to their own needs * Include multiple examples when there are common variations ## Quality checklist Before submitting documentation, verify: * [ ] Opens with value statement (what, why, expectations) * [ ] Uses sentence case for all headings * [ ] No subjective qualifiers or marketing language * [ ] Active voice and present tense throughout * [ ] Direct address using "you" (no "we/us/our") * [ ] Direct imperative instructions (no "you need to") * [ ] Code examples are complete and tested * [ ] All links work and are current * [ ] Ends with actionable next steps * [ ] Terminology matches Vale rules and approved dictionaries ## Examples ### Good opening: ```markdown theme={null} # Set up webhook notifications This guide shows you how to configure webhooks to receive real-time updates when users complete actions in your application. After setting up webhooks, your application can respond immediately to events without polling Writer's API. ``` ### Good closing: ```markdown theme={null} ## Next steps Now that you have webhooks configured, you can: - [Handle webhook failures](link) to ensure reliable event processing - [Secure your webhook endpoints](link) with signature verification - [Set up webhook monitoring](link) to track delivery success ``` ### Voice transformation: ❌ "Our powerful API makes it easy to integrate authentication. We've designed a simple system that will help you get started quickly." ✅ "The authentication API handles user login and token management. Follow these steps to integrate authentication into your application." ❌ "You need to install the Writer SDK before you can start building." ✅ "Install the Writer SDK before building your application." *** *This guide is a living document. Submit suggestions and updates through the standard documentation review process.* --- # Source: https://dev.writer.com/api-reference/kg-api/add-file-to-graph.md > ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # Add file to graph > Add a file to a Knowledge Graph. ## OpenAPI ````yaml post /v1/graphs/{graph_id}/file openapi: 3.0.3 info: title: API version: '1.0' servers: - url: https://api.writer.com security: - bearerAuth: [] paths: /v1/graphs/{graph_id}/file: post: tags: - KG API summary: Add file to graph description: Add a file to a Knowledge Graph. operationId: addFileToGraph parameters: - name: graph_id in: path required: true schema: type: string format: uuid description: The unique identifier of the Knowledge Graph. requestBody: content: application/json: schema: $ref: '#/components/schemas/graph_file_request' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/file_response' example: id: 7c36a365-392f-43ba-840d-8f3103b42572 created_at: '2024-07-10T15:16:10.684826Z' name: example.pdf graph_id: - 50daa3d0-e7d9-44a4-be42-b53e2379ebf7 security: - bearerAuth: [] components: schemas: graph_file_request: title: graph_file_request required: - file_id type: object properties: file_id: type: string description: The unique identifier of the file. file_response: title: file_response required: - id - created_at - name - graph_ids - status type: object properties: id: type: string description: A unique identifier of the file. created_at: type: string format: date-time description: The timestamp when the file was uploaded. name: type: string description: The name of the file. graph_ids: type: array items: type: string format: uuid description: >- A list of Knowledge Graph IDs that the file is associated with. If you provided a `graphId` during upload, the file is associated with that Knowledge Graph. However, the `graph_ids` field in the upload response is an empty list. The association will be visible in the `graph_ids` list when you retrieve the file using the file retrieval endpoint. status: type: string description: The processing status of the file. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer authentication header of the form `Bearer `, where `` is your [Writer API key](https://dev.writer.com/api-reference/api-keys). ```` --- # Source: https://dev.writer.com/api-reference-legacy/terminology/add-terms.md # Add terms ## OpenAPI ````yaml post /terminology/organization/{organizationId}/team/{teamId} paths: path: /terminology/organization/{organizationId}/team/{teamId} method: post servers: - url: https://enterprise-api.writer.com request: security: [] parameters: path: organizationId: schema: - type: integer required: true teamId: schema: - type: integer required: true query: {} header: Authorization: schema: - type: string required: true cookie: {} body: application/json: schemaArray: - type: object properties: models: allOf: - type: array items: $ref: '#/components/schemas/TermCreate' failHandling: allOf: - type: string enum: - accumulate - validate - skip - validateOnly required: true refIdentifier: '#/components/schemas/CreateTermsRequest' examples: example: value: models: - reference: term: type: approved pos: noun caseSensitive: true description: highlight: true examples: - example: type: good mistakes: - reference: mistake: pos: noun caseSensitive: true tags: - tag: linkedTerms: - reference: linkedTermId: 123 approvedTermExtension: capitalize: true fixCommonMistakes: true fixCase: true failHandling: accumulate response: '200': application/json: schemaArray: - type: object properties: models: allOf: - type: array items: $ref: '#/components/schemas/FullTermWithUser' fails: allOf: - type: array items: $ref: '#/components/schemas/FailMessage' refIdentifier: '#/components/schemas/CreateTermsResponse' examples: example: value: models: - id: 123 termBankId: 123 term: type: approved pos: noun caseSensitive: true description: highlight: true creationTime: '2023-11-07T05:31:56Z' modificationTime: '2023-11-07T05:31:56Z' createdUser: id: 123 fullName: email: modifiedUser: id: 123 fullName: email: examples: - id: 123 termId: 123 termBankId: 123 example: type: good mistakes: - id: 123 termId: 123 termBankId: 123 mistake: pos: noun caseSensitive: true tags: - id: 123 tag: termId: 123 parentTagId: 123 linkedTerms: - id: 123 termId: 123 linkedTermId: 123 term: pos: noun caseSensitive: true approvedTermExtension: id: 123 termId: 123 capitalize: true fixCommonMistakes: true fixCase: true backlinkedTerms: - id: 123 termId: 123 linkedTermId: 123 term: pos: noun caseSensitive: true approvedTermExtension: id: 123 termId: 123 capitalize: true fixCommonMistakes: true fixCase: true approvedTermExtension: id: 123 termId: 123 capitalize: true fixCommonMistakes: true fixCase: true fails: - description: key: extras: description: '' '400': application/json: schemaArray: - type: object properties: tpe: allOf: - &ref_0 type: string errors: allOf: - &ref_1 type: array items: $ref: '#/components/schemas/FailMessage' extras: allOf: - &ref_2 $ref: '#/components/schemas/Json' refIdentifier: '#/components/schemas/FailResponse' requiredProperties: &ref_3 - tpe - extras examples: example: value: tpe: errors: - description: key: extras: extras: description: Bad Request '401': application/json: schemaArray: - type: object properties: tpe: allOf: - *ref_0 errors: allOf: - *ref_1 extras: allOf: - *ref_2 refIdentifier: '#/components/schemas/FailResponse' requiredProperties: *ref_3 examples: example: value: tpe: errors: - description: key: extras: extras: description: Unauthorized '403': application/json: schemaArray: - type: object properties: tpe: allOf: - *ref_0 errors: allOf: - *ref_1 extras: allOf: - *ref_2 refIdentifier: '#/components/schemas/FailResponse' requiredProperties: *ref_3 examples: example: value: tpe: errors: - description: key: extras: extras: description: Forbidden '404': application/json: schemaArray: - type: object properties: tpe: allOf: - *ref_0 errors: allOf: - *ref_1 extras: allOf: - *ref_2 refIdentifier: '#/components/schemas/FailResponse' requiredProperties: *ref_3 examples: example: value: tpe: errors: - description: key: extras: extras: description: Not Found '500': application/json: schemaArray: - type: object properties: tpe: allOf: - *ref_0 errors: allOf: - *ref_1 extras: allOf: - *ref_2 refIdentifier: '#/components/schemas/FailResponse' requiredProperties: *ref_3 examples: example: value: tpe: errors: - description: key: extras: extras: description: Internal Server Error deprecated: false type: path components: schemas: ApprovedTermExtensionCreate: required: - capitalize - fixCommonMistakes - fixCase type: object properties: capitalize: type: boolean fixCommonMistakes: type: boolean fixCase: type: boolean TermMistakeCreate: required: - mistake - caseSensitive type: object properties: reference: type: string mistake: type: string pos: type: string enum: - noun - verb - adverb - adjective caseSensitive: type: boolean FailMessage: required: - description - key - extras type: object properties: description: type: string key: type: string extras: $ref: '#/components/schemas/Json' TermTagResponse: required: - id - tag - termId - parentTagId type: object properties: id: type: integer format: int64 tag: type: string termId: type: integer format: int64 parentTagId: type: integer format: int64 TermExample: required: - termId - termBankId - example - type type: object properties: id: type: integer format: int64 termId: type: integer format: int64 termBankId: type: integer format: int64 example: type: string type: type: string enum: - good - bad FullLinkedTerm: required: - termId - linkedTermId - term - caseSensitive type: object properties: id: type: integer format: int64 termId: type: integer format: int64 linkedTermId: type: integer format: int64 term: type: string pos: type: string enum: - noun - verb - adverb - adjective caseSensitive: type: boolean approvedTermExtension: $ref: '#/components/schemas/ApprovedTermExtension' Json: {} LinkedTermCreate: type: object properties: reference: type: string linkedTermId: type: integer format: int64 TermExampleCreate: required: - example - type type: object properties: example: type: string type: type: string enum: - good - bad TermCreate: required: - term - type - caseSensitive type: object properties: reference: type: string term: type: string type: type: string enum: - approved - banned - pending pos: type: string enum: - noun - verb - adverb - adjective caseSensitive: type: boolean description: type: string highlight: type: boolean examples: type: array items: $ref: '#/components/schemas/TermExampleCreate' mistakes: type: array items: $ref: '#/components/schemas/TermMistakeCreate' tags: type: array items: $ref: '#/components/schemas/TermTagCreate' linkedTerms: type: array items: $ref: '#/components/schemas/LinkedTermCreate' approvedTermExtension: $ref: '#/components/schemas/ApprovedTermExtensionCreate' ApprovedTermExtension: required: - termId - capitalize - fixCommonMistakes - fixCase type: object properties: id: type: integer format: int64 termId: type: integer format: int64 capitalize: type: boolean fixCommonMistakes: type: boolean fixCase: type: boolean TermMistake: required: - termId - termBankId - mistake - caseSensitive type: object properties: id: type: integer format: int64 termId: type: integer format: int64 termBankId: type: integer format: int64 mistake: type: string pos: type: string enum: - noun - verb - adverb - adjective caseSensitive: type: boolean TermTagCreate: required: - tag type: object properties: tag: type: string FullTermWithUser: required: - id - termBankId - term - type - caseSensitive - highlight - creationTime - modificationTime - createdUser - modifiedUser type: object properties: id: type: integer format: int64 termBankId: type: integer format: int64 term: type: string type: type: string enum: - approved - banned - pending pos: type: string enum: - noun - verb - adverb - adjective caseSensitive: type: boolean description: type: string highlight: type: boolean creationTime: type: string format: date-time modificationTime: type: string format: date-time createdUser: $ref: '#/components/schemas/TerminologyUser' modifiedUser: $ref: '#/components/schemas/TerminologyUser' examples: type: array items: $ref: '#/components/schemas/TermExample' mistakes: type: array items: $ref: '#/components/schemas/TermMistake' tags: type: array items: $ref: '#/components/schemas/TermTagResponse' linkedTerms: type: array items: $ref: '#/components/schemas/FullLinkedTerm' backlinkedTerms: type: array items: $ref: '#/components/schemas/FullLinkedTerm' approvedTermExtension: $ref: '#/components/schemas/ApprovedTermExtension' TerminologyUser: required: - id type: object properties: id: type: integer format: int64 fullName: type: string email: type: string ```` --- # Source: https://dev.writer.com/blueprints/addfilestowritercloud.md > ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # Add files to Writer Cloud Uploads files to the Writer platform. ## Overview The **Add files to Writer Cloud** block uploads files to the Writer cloud so you can use them in your workflows. It accepts a list of file objects as inputs. ## File inputs The **Add files to Writer Cloud** block accepts a list of file objects as inputs. Each file object must have the following fields: | Field | Type | Description | | ------ | ------ | -------------------------------------------------------------------------------------------------------------- | | `name` | string | The name of the file. | | `data` | bytes | The content of the file as bytes. | | `type` | string | The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) of the file. | ### Adding files from the file input block If you upload a file with the **File input** interface block, the list of file objects is automatically created for you, so all you have to do is pass the list to the **Add files to Writer Cloud** block. See the [example below](#example%3A-upload-files-to-writer-cloud-from-the-file-input-block) for how to do this. You can retrieve the file objects list from the **File input** interface block in two ways: * Connect a UI Trigger to the **File input** block's `wf-file-change` event. Then, use the `@{payload}` environment variable to access the file objects. The trigger will fire when a user adds or removes files from the file input block. * Under **Binding** in the **File input** interface block, define a state variable that contains the list of file objects. Then reference that variable in the **Add files to Writer Cloud** block. ## Output Once the files are uploaded to the Writer cloud, the **Add files to Writer Cloud** block returns a list containing the uploaded file IDs and other information about the files. You can access the output of an **Add files to Writer Cloud** block using the `@{result}` variable in the block that follows it in a blueprint. Each file object has the following fields: | Field | Type | Description | | ------------ | ------ | ----------------------------------------------------------------------- | | `id` | string | The ID of the file. | | `name` | string | The name of the file. | | `status` | string | The status of the file. Can be `in_progress`, `completed`, or `failed`. | | `created_at` | string | The date and time the file was created. | | `graph_ids` | array | The IDs of any Knowledge Graphs that the file is associated with. | ```json theme={null} [ { "id": "701118ae", "name": "research_paper.pdf", "status": "in_progress", "created_at": "2025-06-17T16:18:42.672407+00:00", "graph_ids": [] } ] ``` ### File processing status If the uploaded file's status is `in_progress`, the file is being processed and is not ready to be used in a workflow. Some files are processed quickly, such as PDFs and images, and are ready to be used in a workflow within seconds. Others, such as Word documents, may take a few minutes to process. There are a few ways you can handle files that are still being processed: * Split the blueprint into two parts: one that uploads the files when a user adds them to the file input block, and another that uses the files when a user clicks a button in the UI. This way, you can use the files in the workflow as soon as they're uploaded, and wait for the user to click a button to use the files in the second part of the blueprint. See an example in the [Upload, parse, and summarize PDFs](/agent-builder/summarize-pdfs#build-the-blueprints) tutorial. * Add a Python block that introduces a few seconds of delay before the workflow continues. * Add a [**Tool calling** block](/agent-builder/tool-calling) that can check the status of the file [using the Writer API](/api-reference/file-api/get-file) and wait for the file to be processed before continuing. ## Example: Upload files to Writer Cloud from the file input block This example shows how to upload files to Writer Cloud that are stored in a state variable. In this example, the interface contains a file input block that's bound to the state variable `files`. After the UI Trigger fires, the **Add files to Writer Cloud** block uploads the files to Writer Cloud by accessing the `@{files}` state variable. The `@{files}` state variable looks like this: ```json theme={null} [ { "name": "research_paper.pdf", "data": "...", "type": "application/pdf" } ] ``` ## Example: Create and upload files from Python processing This example shows how to manually create file objects in a **Python code** block and then upload them to Writer Cloud. In this scenario, a Python block generates a CSV report from data processing and creates the file object programmatically. The **Python code** block contains the following code, which creates a CSV file object and returns it as a list for the **Add files to Writer Cloud** block to access. ```python theme={null} import csv import io # Sample data processing data = [ ["Name", "Score", "Category"], ["Product A", 85, "Electronics"], ["Product B", 92, "Home & Garden"], ["Product C", 78, "Electronics"] ] # Create CSV content csv_buffer = io.StringIO() writer = csv.writer(csv_buffer) writer.writerows(data) csv_content = csv_buffer.getvalue() # Convert to bytes csv_bytes = csv_content.encode('utf-8') # Create file object file_object = { "name": "product_analysis.csv", "data": csv_bytes, "type": "text/csv" } # Return the file object as a list (required by Add files to Writer Cloud block) set_output([file_object]) ``` The Python block outputs `[file_object]`, which the **Add files to Writer Cloud** block then accesses using `@{result}` to upload the CSV file. ## Fields
Name Type Control Default Description Options Validation
Files Object - \[] A list of files to be uploaded to the Writer platform. You can use files uploaded via the File input component or specify dictionaries with data, type and name. - -
## End states Below are the possible end states of the block call.
Name Field Type Description
Success - success File successfully uploaded.
Error - error There was an error uploading the files.
Access the output of a **Add files to Writer Cloud** block using the `@{result}` variable in the block that follows it in a blueprint. --- # Source: https://dev.writer.com/blueprints/addtoknowledgegraph.md > ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # Add to Knowledge Graph Adds structured information to the knowledge graph. Use for storing facts AI can reference. ## Overview The **Add to Knowledge Graph** block ingests files into a Writer Knowledge Graph, making the information available for AI-powered search, retrieval, and question answering. You can use this block to build enterprise AI applications that need to reference company documents, policies, or structured data. The Add to Knowledge Graph block only works for Knowledge Graphs that support file uploads. You can't add files to Knowledge Graphs that support data connectors, like Google Drive or Notion, or URLs. **Supported file types:** You can upload `PDF`, `TXT`, `DOC/DOCX`, `PPT/PPTX`, `EML`, `HTML`, `SRT`, `CSV`, or `XLS/XLSX` files to a Knowledge Graph. ## How it works 1. **File selection**: Choose the files to ingest into the Knowledge Graph. 2. **Graph specification**: Select the target Knowledge Graph for ingestion. 3. **Processing**: The block processes and indexes the file content. 4. **Integration**: Files become available for AI-powered queries and retrieval. The block handles the complete process of uploading files to Writer and adding them to the Knowledge Graph, including file validation, content extraction, and indexing. You don't need to upload the files separately or provide file IDs. Once processed, the information becomes searchable through Knowledge Graph queries. ## Examples ### Ingest company policies The following example shows how to add documents to a Knowledge Graph. In this example, the user uploads one or more documents via the [**File Input** interface block](/components/fileinput), which sets the `@{files}` state variable to the user's uploaded files. **Blueprint flow:** 1. **UI Trigger** → User initiates document ingestion with a button click. The **File Input** interface block set the `@{files}` state variable to the user's uploaded file. 2. **Add to Knowledge Graph** → Ingest and add the files from the `@{files}` state variable to the Knowledge Graph. 3. **Set state** → Store whether the files were successfully ingested so the UI can display feedback to the user. **Add to Knowledge Graph block configuration:** * **Graph Id:** `Support KB` * **Files:** `@{files}` ## Fields
Name Type Control Default Description Options Validation
Graph Id Graph Id - - The id for an existing knowledge graph. It has a UUID format. - Format: uuid
Files Object - \[] A list of files to be uploaded and added to the knowledge graph. You can use files uploaded via the File input component or specify dictionaries with data, type and name. - -
URLs Object - \[] A list of URLs to be added to the knowledge graph. Web content from these URLs will be indexed. - -
## End states Below are the possible end states of the block call.
Name Field Type Description
Success - success Content was added to the knowledge graph.
Error - error There was an error adding content to the knowledge graph.
The **Add to Knowledge Graph** block does not return any output. --- # Source: https://dev.writer.com/blueprints/addtostatelist.md > ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # Add to state list Adds a new item to a list in the Agent's state. Useful for tracking multiple values over time. ## Overview This block adds a string value to a list in the agent's state. It behaves differently depending on the state element's type: * If the state element doesn't already exist, the block creates it and adds the value to it. * If the state element already exists as a list, the block adds the value to the list. * If the state element exists but isn't a list, the block fails. The **Add to state list** block only accepts string values. If you pass a value such as a dictionary, it will be converted to a string and added to the list. ## Example The following example shows an **Add to state list** block as part of a **For-each** workflow. The **For-each loop** block iterates over a list of values and generates text for each value. Then, the **Add to state list** block adds the result of each iteration to the state list called `text_gen_results`. On the initial run, the **Add to state list** block creates the state element and adds the first value to it. Every subsequent run, the block adds the next value to the list. ## Fields
Name Type Control Default Description Options Validation
Link Variable Binding - - Set the variable here and use it across your agent. - -
Value Text Textarea - - - -
## End states Below are the possible end states of the block call.
Name Field Type Description
Success - success The item was added to the list.
Error - error There was an error adding the item to the list.
--- # Source: https://dev.writer.com/agent-builder/agent-architecture.md > ## Documentation Index > Fetch the complete documentation index at: https://dev.writer.com/llms.txt > Use this file to discover all available pages before exploring further. # Understand agent architecture > Understand how Agent Builder agents work. Learn about UI components, blueprints, state management, and how they connect to create functional agents.