Workspace API

The workspace API manages folders, projects and the users who own them, and streams project and folder changes as they happen.

Every operation comes with a ready-to-run example: the query, the variables it takes, and the response it returns — see folder for a start.

Queries

folder QUERY

Fetch a single folder by its unique identifier.

folder(
  id: ID!
): Folder

Arguments

folder.id · ID! non-null scalar

The unique identifier of the folder to retrieve.

Type

Folder object

A virtual folder used to organize workspace resources.

folders QUERY

List folders available in the current workspace.

folders(
  limit: Int
  offset: Int
): [Folder!]!

Arguments

folders.limit · Int scalar

Maximum number of folders to return.

folders.offset · Int scalar

Number of folders to skip before returning results.

Type

Folder object

A virtual folder used to organize workspace resources.

projects QUERY

List projects, optionally filtered by lifecycle status.

projects(
  status: ProjectStatus
  limit: Int
): ProjectConnection!

Arguments

projects.status · ProjectStatus enum

Limit results to projects in this lifecycle stage.

projects.limit · Int scalar

Maximum number of projects to return. Defaults to 20.

Type

ProjectConnection object

A paginated project result set.

Search folders, projects, and users from a single endpoint.

search(
  query: String!
): [SearchResult!]!

Arguments

search.query · String! non-null scalar

Text matched against folder, project, and user names.

Type

SearchResult union

A result returned from global workspace search.

Mutations

archiveProject MUTATION

Archive a project that is no longer active.

archiveProject(
  id: ID!
): Project!

Arguments

archiveProject.id · ID! non-null scalar

The unique identifier of the project to archive.

Type

Project object

A unit of work tracked in the workspace.

createFolder MUTATION

Create a virtual folder in the workspace.

createFolder(
  name: String!
  parentId: ID
): Folder!

Arguments

createFolder.name · String! non-null scalar

The name of the new folder.

createFolder.parentId · ID scalar

The optional parent folder identifier.

Type

Folder object

A virtual folder used to organize workspace resources.

createProject MUTATION

Create a project and assign its initial owner.

createProject(
  input: CreateProjectInput!
): Project!

Arguments

createProject.input · CreateProjectInput! non-null input

The project attributes to create.

Type

Project object

A unit of work tracked in the workspace.

Subscriptions

folderCreated SUBSCRIPTION

Receive folders as they are created in the workspace.

folderCreated(
  parentId: ID
): Folder!

Arguments

folderCreated.parentId · ID scalar

Limit events to folders created under this parent.

Type

Folder object

A virtual folder used to organize workspace resources.

projectChanged SUBSCRIPTION

Receive an event whenever a project changes in the workspace.

projectChanged(
  projectId: ID
  types: [ProjectEventType!]
): ProjectEvent!

Arguments

projectChanged.projectId · ID scalar

Limit events to a single project.

projectChanged.types · ProjectEventType! list enum

Limit events to these change kinds.

Type

ProjectEvent object

A change delivered to subscribers watching a project.

Types

Boolean SCALAR

The Boolean scalar type represents true or false.

scalar Boolean

Member Of

include directive · skip directive

CreateProjectInput INPUT

Input used to create a project.

input CreateProjectInput {
  name: String!
  ownerId: ID!
  folderId: ID
  status: ProjectStatus
}

Fields

CreateProjectInput.name · String! non-null scalar

The name for the new project.

CreateProjectInput.ownerId · ID! non-null scalar

The identifier of the user who will own the project.

CreateProjectInput.folderId · ID scalar

The optional folder that will contain the project.

CreateProjectInput.status · ProjectStatus enum

The initial lifecycle stage for the project.

Member Of

createProject mutation

DateTime SCALAR

An ISO 8601 timestamp in UTC.

scalar DateTime

Member Of

Folder object · Project object · ProjectEvent object

deprecated DIRECTIVE

Marks an element of a GraphQL schema as no longer supported.

directive @deprecated(
  reason: String!
) on 
  | FIELD_DEFINITION
  | ARGUMENT_DEFINITION
  | INPUT_FIELD_DEFINITION
  | ENUM_VALUE
  | DIRECTIVE_DEFINITION

Arguments

deprecated.reason · String! non-null scalar

Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted using the Markdown syntax, as specified by CommonMark.

deprecatedType DIRECTIVE

Marks an object type as superseded when standard @deprecated cannot be applied.

directive @deprecatedType(
  reason: String!
) on OBJECT

Arguments

deprecatedType.reason · String! non-null scalar

example DIRECTIVE

Provides a GraphQL example that is rendered in the generated API reference.

directive @example(
  value: String!
) on 
  | FIELD_DEFINITION
  | OBJECT

Arguments

example.value · String! non-null scalar

exampleResponse DIRECTIVE

Provides the JSON response returned by the @example operation, rendered alongside it in the generated API reference.

directive @exampleResponse(
  value: String!
) on FIELD_DEFINITION

Arguments

exampleResponse.value · String! non-null scalar

exampleVariables DIRECTIVE

Provides the JSON variables sent with the @example operation, rendered under it in the generated API reference.

directive @exampleVariables(
  value: String!
) on FIELD_DEFINITION

Arguments

exampleVariables.value · String! non-null scalar

Folder OBJECT

A virtual folder used to organize workspace resources.

type Folder implements Node {
  id: ID!
  name: String!
  parent: String
  createdAt: DateTime!
}

Fields

Folder.id · ID! non-null scalar

The unique identifier of the folder.

Folder.name · String! non-null scalar

The human-readable folder name.

Folder.parent · String scalar

The identifier of the parent folder, when nested.

Folder.createdAt · DateTime! non-null scalar

When the folder was created.

Interfaces

Node interface

A globally unique entity identifier.

Returned By

createFolder mutation · folder query · folderCreated subscription · folders query

Member Of

Project object

Implemented By

SearchResult union

ID SCALAR

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

scalar ID

Member Of

archiveProject mutation · createFolder mutation · CreateProjectInput input · Folder object · folder query · folderCreated subscription · LegacyProject object · Node interface · Project object · projectChanged subscription · User object

include DIRECTIVE

Directs the executor to include this field or fragment only when the if argument is true.

directive @include(
  if: Boolean!
) on 
  | FIELD
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT

Arguments

include.if · Boolean! non-null scalar

Included when true.

Int SCALAR

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

scalar Int

Member Of

folders query · ProjectConnection object · projects query

LegacyProject OBJECT

deprecatedReplaced by `Project` to support ownership and lifecycle status.

deprecated

Use Project instead for active workspace work.

type LegacyProject {
  id: ID!
  name: String!
}

Fields

LegacyProject.id · ID! non-null scalar

The unique identifier of the legacy project.

LegacyProject.name · String! non-null scalar

The legacy project name.

Node INTERFACE

A globally unique entity identifier.

interface Node {
  id: ID!
}

Fields

Node.id · ID! non-null scalar

The globally unique identifier for this resource.

Implemented By

Folder object · Project object · User object

oneOf DIRECTIVE

Indicates exactly one field must be supplied and this field must not be null.

directive @oneOf on INPUT_OBJECT

Project OBJECT

A unit of work tracked in the workspace.

type Project implements Node {
  id: ID!
  name: String!
  status: ProjectStatus!
  owner: User!
  folder: Folder
  updatedAt: DateTime!
  state: String @deprecated
}

Fields

Project.id · ID! non-null scalar

The unique identifier of the project.

Project.name · String! non-null scalar

The project name shown to collaborators.

Project.status · ProjectStatus! non-null enum

The current lifecycle stage of the project.

Project.owner · User! non-null object

The user responsible for the project.

Project.folder · Folder object

The folder containing this project, when assigned.

Project.updatedAt · DateTime! non-null scalar

When the project was last updated.

Project.state · String deprecated scalar

The project's lifecycle stage.

Interfaces

Node interface

A globally unique entity identifier.

Returned By

archiveProject mutation · createProject mutation

Member Of

ProjectConnection object · ProjectEvent object

Implemented By

SearchResult union

ProjectConnection OBJECT

A paginated project result set.

type ProjectConnection {
  nodes: [Project!]!
  totalCount: Int!
}

Fields

ProjectConnection.nodes · Project!! non-null object

Projects in the current result page.

ProjectConnection.totalCount · Int! non-null scalar

The total number of projects matching the query.

Returned By

projects query

ProjectEvent OBJECT

A change delivered to subscribers watching a project.

type ProjectEvent {
  type: ProjectEventType!
  project: Project!
  actor: User
  occurredAt: DateTime!
}

Fields

ProjectEvent.type · ProjectEventType! non-null enum

The kind of change that occurred.

ProjectEvent.project · Project! non-null object

The project in its state after the change.

ProjectEvent.actor · User object

The user who triggered the change, when known.

ProjectEvent.occurredAt · DateTime! non-null scalar

When the change occurred.

Returned By

projectChanged subscription

ProjectEventType ENUM

The kind of change that occurred on a project.

enum ProjectEventType {
  CREATED
  UPDATED
  ARCHIVED
}

Values

ProjectEventType.CREATED

The project was created.

ProjectEventType.UPDATED

One or more project fields were updated.

ProjectEventType.ARCHIVED

The project was archived.

Member Of

projectChanged subscription · ProjectEvent object

ProjectStatus ENUM

The lifecycle stage of a project.

enum ProjectStatus {
  DRAFT
  ACTIVE
  ARCHIVED
}

Values

ProjectStatus.DRAFT

The project is being planned and is not yet active.

ProjectStatus.ACTIVE

The project is active and available to collaborators.

ProjectStatus.ARCHIVED

The project is retained for history and no longer active.

Member Of

CreateProjectInput input · Project object · projects query

SearchResult UNION

A result returned from global workspace search.

union SearchResult = Folder | Project | User

Possible types

SearchResult.Folder object

A virtual folder used to organize workspace resources.

SearchResult.Project object

A unit of work tracked in the workspace.

SearchResult.User object

A workspace member who owns and collaborates on projects.

Returned By

search query

skip DIRECTIVE

Directs the executor to skip this field or fragment when the if argument is true.

directive @skip(
  if: Boolean!
) on 
  | FIELD
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT

Arguments

skip.if · Boolean! non-null scalar

Skipped when true.

specifiedBy DIRECTIVE

Exposes a URL that specifies the behavior of this scalar.

directive @specifiedBy(
  url: String!
) on SCALAR

Arguments

specifiedBy.url · String! non-null scalar

The URL that specifies the behavior of this scalar.

String SCALAR

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

scalar String

Member Of

createFolder mutation · CreateProjectInput input · deprecated directive · deprecatedType directive · example directive · exampleResponse directive · exampleVariables directive · Folder object · LegacyProject object · Project object · search query · specifiedBy directive · User object

User OBJECT

A workspace member who owns and collaborates on projects.

type User implements Node {
  id: ID!
  name: String!
  email: String!
  role: String!
}

Fields

User.id · ID! non-null scalar

The unique identifier of the user.

User.name · String! non-null scalar

The user's display name.

User.email · String! non-null scalar

The user's primary email address.

User.role · String! non-null scalar

The user's role in the workspace.

Interfaces

Node interface

A globally unique entity identifier.

Member Of

Project object · ProjectEvent object

Implemented By

SearchResult union