List Prompt Folders

Retrieve prompt folders in your workspace

Returns prompt folders you can access in your workspace. Use query parameters to paginate, search, or filter by workspace sharing.

Base URL

https://api.ajan.io/prompts/v1/folders

Required Scopes

This endpoint requires the PROMPT_API scope.

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of folders to return. Default: `50`. Maximum: `250`.
`cursor`	string	No	Cursor from the previous response for pagination.
`query`	string	No	Search query matched against folder name.
`sharedWithWorkspace`	string	No	Filter by workspace sharing. Allowed values: `true`, `false`.

Example

javascript

const axios = require("axios");

async function listPromptFolders() {
  const response = await axios.get("https://api.ajan.io/prompts/v1/folders", {
    params: {
      limit: 25,
      query: "support"
    },
    headers: {
      Authorization: "Bearer YOUR_API_KEY"
    }
  });

  console.log("Folders:", response.data.folders);
  return response.data.nextCursor;
}

listPromptFolders();

Response Format

Success Response (200 OK)

typescript

{
  folders: Array<{
    id: string;
    name: string;
    createdBy: string;
    sharedWithWorkspace: boolean;
    sharedWithGroupId: string | null;
    createdAt: string;
    updatedAt: string;
  }>;
  nextCursor?: string;
}

Example Response

json

{
  "folders": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Support templates",
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "sharedWithWorkspace": false,
      "sharedWithGroupId": null,
      "createdAt": "2026-07-28T10:30:00.000Z",
      "updatedAt": "2026-07-28T10:30:00.000Z"
    }
  ],
  "nextCursor": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Error Handling

Status Code	Description
400	Invalid query parameter
401	Invalid or missing API key
403	Missing `PROMPT_API` scope or workspace access
429	Rate limit exceeded
500	Internal server error

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /prompts/v1/folders:
    get:
      tags:
        - Prompts
      summary: List prompt folders
      description: Returns prompt folders you can access in your workspace.
      operationId: listPromptFolders
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 50
          description: Number of folders to return.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Cursor from the previous response for pagination.
        - name: query
          in: query
          required: false
          schema:
            type: string
          description: Search query matched against folder name.
        - name: sharedWithWorkspace
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Filter by workspace sharing.
      responses:
        '200':
          description: Prompt folders returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPromptFoldersResponse'
        '400':
          description: Invalid query parameter
        '401':
          description: Invalid or missing API key
        '403':
          description: Missing required scope or access
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
components:
  schemas:
    ListPromptFoldersResponse:
      type: object
      required:
        - folders
      properties:
        folders:
          type: array
          items:
            $ref: '#/components/schemas/PromptFolder'
        nextCursor:
          type: string
          format: uuid
          description: Cursor for the next page, if more results are available.
    PromptFolder:
      type: object
      required:
        - id
        - name
        - createdBy
        - sharedWithWorkspace
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the prompt folder.
        name:
          type: string
          minLength: 2
          maxLength: 50
          description: Folder name.
        createdBy:
          type: string
          format: uuid
          description: User ID of the folder creator.
        sharedWithWorkspace:
          type: boolean
          description: Whether the folder is shared with the workspace.
        sharedWithGroupId:
          type: string
          format: uuid
          nullable: true
          description: Group ID the folder is shared with.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp for folder creation.
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp for the latest folder update.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"