Documentation

Integrate promptman with your AI applications using the Model Context Protocol (MCP) server or REST API. Manage, version, and deploy your prompts programmatically.

Quick Start

To use the promptman API, you'll need an API key. Sign up for a free account to get started.

Create Free Account

Model Context Protocol

MCP Server Integration

Promptman exposes a standard MCP server that allows AI agents (like Claude Desktop or Claude Code) to discover, fetch, and manage your prompts dynamically as tools.

Server URL

https://api.promptman.dev/mcp

Configuration

{
  "mcpServers": {
    "promptman": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.promptman.dev/mcp",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}

Add this to claude_desktop_config.json (Claude Desktop) or ~/.claude/settings.json (Claude Code). Replace YOUR_API_KEY with your API key from the dashboard.

Prompt Tools

list_prompts

Tool

Returns a list of all prompts in your workspace. Can optionally filter by a specific app.

Input Schema

Argument	Type	Description	Required
appSlug	string	Filter prompts by app slug	No

get_prompt

Tool

Retrieves a specific prompt by its slug. Optionally specify a stage to get the version pinned to that deployment stage. Without a stage, returns the latest draft.

Input Schema

Argument	Type	Description	Required
promptSlug	string	The slug of the prompt to retrieve	Yes
stage	string	Stage name (e.g., 'dev', 'prod') to get the pinned version	No

list_apps

Tool

Returns a list of all applications in your workspace.

Input Schema

No arguments required.

get_prompt_versions

Tool

Returns the version history of a specific prompt, ordered by most recent first.

Input Schema

Argument	Type	Description	Required
promptSlug	string	The slug of the prompt	Yes
limit	number	Maximum number of versions to return (default: 20)	No

create_prompt

Tool

Creates a new prompt in the specified application.

Input Schema

Argument	Type	Description	Required
appSlug	string	The slug of the app to create the prompt in	Yes
content	string	The content/text of the prompt	Yes
title	string	The title of the prompt (max 200 characters)	No
variableDescriptions	object	Descriptions for template variables (see Variables Schema below)	No

update_prompt

Tool

Updates an existing prompt's title and/or content. Does not create a new version by default.

Input Schema

Argument	Type	Description	Required
promptSlug	string	The slug of the prompt to update	Yes
title	string	The new title of the prompt	Yes
content	string	The new content/text of the prompt	Yes
variableDescriptions	object	Descriptions for template variables (see Variables Schema below)	No
createVersion	boolean	Whether to create a new version (default: false)	No

delete_prompt

Tool

Permanently deletes a prompt and all its versions. This action cannot be undone.

Input Schema

Argument	Type	Description	Required
promptSlug	string	The slug of the prompt to delete	Yes

Agent Tools

list_agents

Tool

Returns a list of all agents in your workspace. Can optionally filter by a specific app.

Input Schema

Argument	Type	Description	Required
appSlug	string	Filter agents by app slug	No

get_agent_context

Tool

Retrieves all documents for an agent. Optionally specify a stage to get the versions pinned to that deployment stage. Without a stage, returns the latest drafts.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent to retrieve	Yes
stage	string	Stage name (e.g., 'dev', 'prod') to get the pinned versions	No

create_agent

Tool

Creates a new agent in the specified application.

Input Schema

Argument	Type	Description	Required
appSlug	string	The slug of the app to create the agent in	Yes
name	string	The name of the agent (max 200 characters)	Yes
description	string	A description of the agent	No

update_agent

Tool

Updates an existing agent's name and/or description.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent to update	Yes
name	string	The new name of the agent	No
description	string	The new description of the agent	No

delete_agent

Tool

Permanently deletes an agent and all its documents and versions. This action cannot be undone.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent to delete	Yes

get_agent_document

Tool

Retrieves a specific document from an agent by its document key. Optionally specify a stage to get the pinned version.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent	Yes
documentKey	string	The document key (e.g., 'SOUL.md', 'AGENTS.md')	Yes
stage	string	Stage name to get the pinned version	No

create_agent_document

Tool

Creates a new document in an agent. Documents are identified by their key (e.g., 'SOUL.md', 'AGENTS.md').

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent	Yes
documentKey	string	The document key (e.g., 'SOUL.md')	Yes
content	string	The content of the document	Yes

update_agent_document

Tool

Updates an existing agent document's content. Does not create a new version by default.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent	Yes
documentKey	string	The document key	Yes
content	string	The new content of the document	Yes
createVersion	boolean	Whether to create a new version (default: false)	No
message	string	Version message (required when createVersion is true, max 200 characters)	No

delete_agent_document

Tool

Permanently deletes a document from an agent, including all its versions. This action cannot be undone.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent	Yes
documentKey	string	The document key to delete	Yes

get_agent_document_versions

Tool

Returns the version history of a specific agent document, ordered by most recent first.

Input Schema

Argument	Type	Description	Required
agentSlug	string	The slug of the agent	Yes
documentKey	string	The document key	Yes
limit	number	Maximum number of versions to return (default: 20)	No

REST API

Use the REST API to fetch prompts directly in your applications. Perfect for server-side integrations and custom workflows.

Base URL

https://api.promptman.dev

Authentication

All API requests require an API key passed in the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" \
     https://api.promptman.dev/prompt/welcome-email

Endpoints

GET

/v1/prompts/:slug

Retrieve a prompt by its slug. Returns the latest draft version by default.

Parameters

Parameter	Location	Description	Required
slug	path	The slug of the prompt	Yes
app	query	App slug to validate the prompt belongs to this app	No
stage	query	Stage name to get the pinned version (e.g., 'dev', 'prod')	No

Response

{
  "title": "Welcome Email",
  "content": "Hello {{username}}, welcome to {{company}}!",
  "variables": {
    "username": { "required": true, "type": "string", "description": "..." },
    "company": { "required": true, "type": "string", "description": "..." }
  },
  "version": 3
}

GET

/v1/agents/:slug

Retrieve all documents for an agent by its slug. Returns the latest drafts by default.

Parameters

Parameter	Location	Description	Required
slug	path	The slug of the agent	Yes
app	query	App slug to validate the agent belongs to this app	No
stage	query	Stage name to get the pinned versions (e.g., 'dev', 'prod')	No

Response

{
  "name": "My Agent",
  "description": "Agent description",
  "documents": {
    "SOUL.md": "# Soul\nYou are...",
    "AGENTS.md": "# Agents\n..."
  }
}

Variables Schema

Prompts can contain template variables using the {{variableName}} syntax. When creating or updating prompts, you can provide descriptions for these variables.

Input Format (when creating/updating)

The variableDescriptions parameter accepts a simple object mapping variable names to their descriptions:

variableDescriptions

{
  "username": "The user's display name",
  "email": "User's email address",
  "company": "The company or organization name"
}

Output Format (in responses)

When retrieving prompts, the API returns a structured variables object with additional metadata for each variable:

variables

{
  "username": {
    "required": true,
    "type": "string",
    "description": "The user's display name"
  },
  "email": {
    "required": true,
    "type": "string",
    "description": "User's email address"
  }
}

Variable extraction

Variables are automatically extracted from the prompt content by scanning for {{variableName}} patterns. Variable names are normalized to lowercase. Only variables that appear in the content will be included in the response.