# GraphQL API Overview {#graphql-api-overview}


Using the Gauzy GraphQL API alongside the REST API.


## Endpoint {#endpoint}


```
POST /graphql
```

GraphQL Playground: `http://localhost:3000/graphql`


## Authentication {#authentication}


Include JWT token in the request headers:

```json
{
  "Authorization": "Bearer YOUR_TOKEN"
}
```


## Example Queries {#example-queries}



### Fetch Employees {#fetch-employees}


```graphql
query {
  employees(
    filter: { organizationId: "org-uuid", isActive: true }
    paging: { limit: 10, offset: 0 }
  ) {
    edges {
      node {
        id
        user {
          firstName
          lastName
          email
        }
        startedWorkOn
        isActive
      }
    }
    totalCount
  }
}
```


### Fetch Tasks {#fetch-tasks}


```graphql
query {
  tasks(
    filter: { projectId: "project-uuid", status: "TODO" }
    sorting: [{ field: createdAt, direction: DESC }]
  ) {
    edges {
      node {
        id
        title
        status
        priority
        assignees {
          id
          user {
            firstName
            lastName
          }
        }
      }
    }
    totalCount
  }
}
```


## Mutations {#mutations}



### Create Task {#create-task}


```graphql
mutation {
  createOneTask(
    input: {
      task: {
        title: "New Task via GraphQL"
        status: "TODO"
        priority: "HIGH"
        projectId: "project-uuid"
        organizationId: "org-uuid"
        tenantId: "tenant-uuid"
      }
    }
  ) {
    id
    title
    status
  }
}
```


### Update Employee {#update-employee}


```graphql
mutation {
  updateOneEmployee(
    input: { id: "employee-uuid", update: { isActive: false } }
  ) {
    id
    isActive
  }
}
```


## Subscriptions {#subscriptions}


```graphql
subscription {
  timerStatusChanged {
    employeeId
    running
    duration
  }
}
```


## GraphQL vs REST {#graphql-vs-rest}


| Feature        | GraphQL                | REST                |
| -------------- | ---------------------- | ------------------- |
| Data fetching  | Client specifies shape | Fixed responses     |
| Over-fetching  | No                     | Common              |
| Under-fetching | No                     | Requires joins      |
| Typing         | Strong schema          | OpenAPI/Swagger     |
| Caching        | More complex           | Standard HTTP cache |


## Related Pages {#related-pages}


- [API Overview](https://sourcey-gauzy.pages.dev/api/overview/index.md) — REST API
- [Pagination & Filtering](https://sourcey-gauzy.pages.dev/api/pagination-and-filtering/index.md) — query patterns