# Create Document — Linear (API key)

> Create a new Linear document (a spec, brief, runbook or meeting notes) and attach it to exactly one project, initiative, team or issue so teammates can find it. Set exactly one of projectId, initiativeId, teamId or issueId. If the user did…

- Key: `linear_app-create-document`
- Type: Action (Write)
- Version: 0.0.2
- App: Linear (API key) (`linear_app`) — https://pipedream.com/apps/linear-app.md
- This page (HTML): https://pipedream.com/apps/linear-app/actions/create-document
- Hints: open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/linear_app/actions/create-document/create-document.mjs

## Description

Create a new Linear document (a spec, brief, runbook or meeting notes) and attach it to exactly one project, initiative, team or issue so teammates can find it. Set exactly one of `projectId`, `initiativeId`, `teamId` or `issueId`. If the user did not say where the document belongs and the choice is ambiguous, ask them before calling this tool rather than guessing. Use **List Projects**, **List Initiatives**, **Get Teams** or **Search Issues** to look up the ID. To change an existing document, use **Update Document** instead; to check whether a document already exists, use **Search Documents**. `content` is markdown. The response does not echo the body back; use **Get Document** to read it. Example: `title: "Dust Storm Shelter Spec"`, `content: "# Overview\n\nShelter requirements..."`, `projectId: "a1b2c3d4-0000-0000-0000-000000000001"` → returns `{success: true, document: {id: "29a25062-...", title: "Dust Storm Shelter Spec", slugId: "10b5bc2940c7", url: "https://linear.app/.../document/dust-storm-shelter-spec-10b5bc2940c7", project: {id: "a1b2c3d4-...", name: "Mars Colony"}}}`. [See the documentation](https://studio.apollographql.com/public/Linear-API/variant/current/schema/reference/objects/Mutation?query=documentCreate)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | The title of the document. Example: Q3 Hiring Plan. |
| `content` | `string` | No | The document body in markdown. Example: # Goals\n\n- Hire two engineers. |
| `projectId` | `string` | No | The UUID or identifier of the project to attach the document to (e.g. a1b2c3d4-0000-0000-0000-000000000001 or P-LIN-123). Set exactly one of projectId, initiativeId, teamId or issueId. Use List Projects to find valid project IDs. |
| `initiativeId` | `string` | No | The UUID or identifier of the initiative to attach the document to (e.g. b2c3d4e5-0000-0000-0000-000000000002 or I-12). Set exactly one of projectId, initiativeId, teamId or issueId. Use List Initiatives to find valid initiative IDs. |
| `teamId` | `string` | No | The UUID of the team to attach the document to (e.g. 9d1c3f7e-2b48-4c6a-9f1e-5a7b8c9d0e1f). The short team key such as ENG is rejected. Set exactly one of projectId, initiativeId, teamId or issueId. Use Get Teams to find valid team IDs. |
| `issueId` | `string` | No | The UUID or identifier of the issue to attach the document to (e.g. 7df5e7f9-a357-4539-ae94-4a004fec635f or ENG-123). Set exactly one of projectId, initiativeId, teamId or issueId. Use Search Issues to find valid issues. |
| `ownerId` | `string` | No | The UUID of the user who owns the document (e.g. abc12345-0000-0000-0000-000000000001). Use List Users to find valid user IDs. |
| `icon` | `string` | No | The document icon, as an emoji shortcode. Raw emoji such as 📄 are rejected. Example: :page_facing_up:. |
| `color` | `string` | No | The color of the document icon, as a hex code. Example: #5e6ad2. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "linear_app",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "linear_app-create-document",
  arguments: {
    title: "Title",
    content: "Content",
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "linear_app-create-document",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    linear_app: { authProvisionId: "apn_xxxxxxx" },
    title: "Title",
    content: "Content",
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "linear_app-create-document",
    "configured_props": {
      "linear_app": { "authProvisionId": "apn_xxxxxxx" },
      "title": "Title",
      "content": "Content"
    }
  }'
```

---

- App: https://pipedream.com/apps/linear-app.md · All apps: https://pipedream.com/apps