Skip to main content

Getting Started with the GQueues API

Written by Jeff

The GQueues API allows you to programmatically manage your queues and tasks. You can list queues, categories, and teams; list and search tasks; create tasks, sections, and queues; and update, complete, snooze, move, and delete tasks from any tool that can make HTTP requests.

See the API Reference for full details on these endpoints.

❗️Please Note: The MCP is now the recommended integration for AI assistants.

To connect an AI assistant (Claude, ChatGPT, Gemini, and others) to GQueues, use the GQueues MCP server instead — it's simpler to set up and requires no token/skill-file wiring. We recommend using the API for custom projects only.

Setup

Create an Access Token

Access tokens authenticate your API requests. Each token is a secret credential tied to your account - treat it like a password.

❗️Please note: Your access token will only be shown once. You should wait to create a token until you are prepared to safely use it or store it.

  1. Open the API settings

    In GQueues Settings, navigate to the API tab.

  2. Enter a label and create the token

    Type a descriptive name (e.g. "My Script") into the Token Name field. Names help you identify what each token is used for. Then click Generate Token.

    To add a token, from the API tab in GQueues, add a name in the Token field and select Generate token

  3. Copy the token immediately

    The full token is shown only once. It will appear in a highlighted box with a Copy button. Click Copy to copy it to your clipboard, then paste it into your tool's configuration.
    ​

    Once the token appears, click the Copy button and paste into your tool's configuration or otherwise store it securely

❗️Please Note: If you close or navigate away before copying the token, you will need to create a new one. For security, the original value cannot be retrieved.

Token List Fields

After creating tokens, the Active Tokens section shows all tokens with the following information:

Field

Description

Label

The name you gave the token when you created it (e.g. "Claude Desktop"). Helps you identify which tool or integration is using each token. If no label was provided, it shows "Unnamed".

Created

The date the token was created (e.g. "Apr 9, 2025"). Useful for auditing and knowing how old a token is.

Expires

The date the token will automatically stop working. Tokens are valid for 10 years by default. After expiration, you will need to create a new token.

Last used

The date the token was last used to make a successful API call (e.g. "Apr 9, 2025"), or "Never" if the token has not been used yet. Helps you identify unused tokens that can be safely revoked.

Revoke button

Permanently disables the token. Any application using this token will immediately lose access. This action cannot be undone -- you will need to create a new token and update your integration.

Token Limits

  • You can have up to 10 tokens per account.

  • Token names can be up to 100 characters long.

  • Tokens expire after 10 years.

  • Revoking a token frees up a slot for creating a new one.

Security Best Practices

  • Create a separate token for each tool or integration. This way, if one is compromised, you can revoke it without affecting others.

  • Never share tokens in emails, chat messages, or source code repositories.

  • Regularly review the Last used date. If a token hasn't been used in a long time and you no longer need it, revoke it.

  • If you suspect a token has been compromised, revoke it immediately from Settings.

Using the API

API Reference

For full specification on every endpoint, parameter, header, and response format, please view the API Reference article.

The Quick-Add Syntax article is the reference for setting due dates, tags, queues, notes, and assignments using natural-language text strings.

Quick Start: Your First API Call

After creating a token, you can test that everything works by making a few simple API calls.

API calls are commands you run in your computer's terminal (also called "command line" or "command prompt") — not in a browser or chat app. To open it:

  • Mac: Open the app called Terminal (search for it in Spotlight)

  • Windows: Open Command Prompt or PowerShell (search from the Start menu)

Once you have a terminal open, paste the following command to list your queues. Replace gq_your_token_here with the token you created:

# Replace with your actual token
curl -s "https://api.gqueues.com/v1?action=getQueues&scope=personal" \
  -H "Authorization: Bearer gq_your_token_here" | python3 -m json.tool

If everything is set up correctly, you should see your queues printed as formatted text.

To create a task, paste this command (again replacing gq_your_token_here with your actual token):

curl -s -X POST "https://api.gqueues.com/v1" \
  -H "Authorization: Bearer gq_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-task-001" \
  -d '{
    "action": "createTask",
    "instructions": [
      {"text": "Try the GQueues API"}
    ]
  }' | python3 -m json.tool

You should see a confirmation with the details of the task that was created. Note that because this command doesn't specify a queue, the task will be created in your Inbox.
​

What's Next?

Did this answer your question?