List Prompts

Retrieve prompts in your workspace

Returns prompts you can access in your workspace. Use query parameters to paginate, search, or filter by folder and workspace sharing.

Base URL

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

Required Scopes

This endpoint requires the PROMPT_API scope.

Parameters

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

Example

javascript

const axios = require("axios");

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

  console.log("Prompts:", response.data.prompts);
  return response.data.nextCursor;
}

listPrompts();

Response Format

Success Response (200 OK)

typescript

{
  prompts: Array<{
    id: string;
    title: string;
    prompt: string;
    createdBy: string | null;
    promptFolderId: string | null;
    sharedWithWorkspace: boolean;
    createdAt: string | null;
    updatedAt: string | null;
  }>;
  nextCursor?: string;
}

Example Response

json

{
  "prompts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Support Reply",
      "prompt": "Write a concise customer reply. Include the next best action.",
      "createdBy": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "promptFolderId": null,
      "sharedWithWorkspace": true,
      "createdAt": "2026-07-28T10:30:00.000Z",
      "updatedAt": "2026-07-28T10:30:00.000Z"
    }
  ],
  "nextCursor": "550e8400-e29b-41d4-a716-446655440000"
}

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:
    get:
      tags:
        - Prompts
      summary: List prompts
      description: Returns prompts you can access in your workspace.
      operationId: listPrompts
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 50
          description: Number of prompts 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 prompt title and content.
        - name: promptFolderId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by prompt folder UUID.
        - name: sharedWithWorkspace
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Filter by workspace sharing.
      responses:
        '200':
          description: Prompts returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPromptsResponse'
        '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:
    ListPromptsResponse:
      type: object
      required:
        - prompts
      properties:
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/Prompt'
        nextCursor:
          type: string
          format: uuid
          description: Cursor for the next page, if more results are available.
    Prompt:
      type: object
      required:
        - id
        - title
        - prompt
        - sharedWithWorkspace
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the prompt.
        title:
          type: string
          minLength: 2
          maxLength: 100
          description: Prompt title.
        prompt:
          type: string
          minLength: 2
          maxLength: 120000
          description: Prompt content.
        createdBy:
          type: string
          format: uuid
          nullable: true
          description: User ID of the prompt creator.
        promptFolderId:
          type: string
          format: uuid
          nullable: true
          description: Folder ID the prompt is assigned to.
        sharedWithWorkspace:
          type: boolean
          description: Whether the prompt is shared with the workspace.
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 timestamp for prompt creation.
        updatedAt:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 timestamp for the latest prompt update.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"