> ## 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.
# Create graph
> Create a new Knowledge Graph.
By default, the new Knowledge Graph is org-wide (accessible to every team in the organization). To deploy the Knowledge Graph to specific teams instead, provide a `team_ids` array in the request body. When the request is authenticated with a team-scoped API key, the new Knowledge Graph is automatically assigned to that key's team and `team_ids` in the body is not accepted.
Knowledge Graphs can be deployed org-wide (accessible to every team in the organization) or [deployed to specific teams](https://support.writer.com/article/242-how-to-create-and-manage-a-knowledge-graph#Managing-a-Knowledge-Graph-R4Mg5). Both are accessible via the API and SDK.
* **With an org-scoped API key**, control team scope from the request body: pass `team_ids` on [create](/api-reference/kg-api/create-graph) or [update](/api-reference/kg-api/update-graph), or filter [list](/api-reference/kg-api/list-graphs) with the `team_ids` query parameter. Omit `team_ids` on list to see only org-wide Knowledge Graphs.
* **With a team-scoped API key**, every request is automatically restricted to the key's team. Create assigns to that team; list and retrieve return only that team's Knowledge Graphs; body `team_ids` is not accepted.
## OpenAPI
````yaml post /v1/graphs
openapi: 3.0.3
info:
title: API
version: '1.0'
servers:
- url: https://api.writer.com
security:
- bearerAuth: []
paths:
/v1/graphs:
post:
tags:
- KG API
summary: Create graph
description: >-
Create a new Knowledge Graph.
By default, the new Knowledge Graph is org-wide (accessible to every
team in the organization). To deploy the Knowledge Graph to specific
teams instead, provide a `team_ids` array in the request body. When the
request is authenticated with a team-scoped API key, the new Knowledge
Graph is automatically assigned to that key's team and `team_ids` in the
body is not accepted.
operationId: createGraph
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/graph_request'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/graph_response'
example:
id: 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
created_at: '2024-07-10T13:34:28.301201Z'
name: Example Knowledge Graph
description: Example description
urls: null
team_ids: []
security:
- bearerAuth: []
x-codeSamples:
- lang: cURL
source: |-
curl --location --request POST https://api.writer.com/v1/graphs \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data-raw '{"name":"string"}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const graph = await client.graphs.create({ name: 'name' });
console.log(graph.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
graph = client.graphs.create(
name="name",
)
print(graph.id)
components:
schemas:
graph_request:
title: graph_request
type: object
properties:
name:
type: string
description: >-
The name of the Knowledge Graph (max 255 characters). Omitting this
field leaves the name unchanged.
description:
type: string
description: >-
A description of the Knowledge Graph (max 255 characters). Omitting
this field leaves the description unchanged.
team_ids:
type: array
description: >-
Optional list of team IDs to deploy the Knowledge Graph to. Omit the
field or pass an empty array to create an org-wide Knowledge Graph
(accessible to every team in the organization), which is the
default. Provide one or more team IDs to scope the Knowledge Graph
to those teams. Only applies when using an org-scoped API key;
requests made with a team-scoped API key ignore this field and
always assign the graph to that key's team.
items:
type: integer
format: int64
graph_response:
title: graph_response
required:
- id
- created_at
- name
type: object
properties:
id:
type: string
format: uuid
description: A unique identifier of the Knowledge Graph.
created_at:
type: string
format: date-time
description: The timestamp when the Knowledge Graph was created.
name:
type: string
description: The name of the Knowledge Graph (max 255 characters).
description:
type: string
description: A description of the Knowledge Graph (max 255 characters).
urls:
type: array
description: An array of web connector URLs associated with this Knowledge Graph.
items:
$ref: '#/components/schemas/web_connector_url'
team_ids:
type: array
description: >-
The team IDs the Knowledge Graph is deployed to. An empty array
indicates an org-wide Knowledge Graph accessible to every team in
the organization.
items:
type: integer
format: int64
web_connector_url:
title: web_connector_url
required:
- url
- status
- type
type: object
properties:
url:
type: string
description: The URL to be processed by the web connector.
status:
$ref: '#/components/schemas/web_connector_url_state'
description: The current status of the URL processing.
exclude_urls:
type: array
description: >-
An array of URLs to exclude from processing within this web
connector.
items:
type: string
type:
$ref: '#/components/schemas/web_connector_url_type'
description: The type of web connector processing for this URL.
web_connector_url_state:
title: web_connector_url_state
description: The state of a web connector URL processing.
required:
- status
type: object
properties:
status:
$ref: '#/components/schemas/web_connector_url_status'
description: The current status of the URL processing.
error_type:
$ref: '#/components/schemas/web_connector_url_error_type'
description: The type of error that occurred during processing, if any.
web_connector_url_type:
title: web_connector_url_type
description: The type of web connector processing for a URL.
type: string
enum:
- single_page
- sub_pages
web_connector_url_status:
title: web_connector_url_status
description: The status of web connector URL processing.
type: string
enum:
- validating
- success
- error
web_connector_url_error_type:
title: web_connector_url_error_type
description: The type of error that can occur during web connector URL processing.
type: string
enum:
- invalid_url
- not_searchable
- not_found
- paywall_or_login_page
- unexpected_error
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).
````