GraphQL Schema

Complete reference for the Prompt Forge GraphQL API. All queries, mutations, and types documented.

The GraphQL endpoint is available at https://api.promptforge.sh/graphql. Don't forget to include your API key in the Authorization header.

Queries

query

me

Get the currently authenticated user's information

query GetMe {
  me {
    id
    email
    name
    createdAt
  }
}

query

prompt(id: ID!)

Fetch a single prompt by ID with all versions and execution history

query GetPrompt($id: ID!) {
  prompt(id: $id) {
    id
    name
    description
    category
    isPublic
    versions {
      id
      version
      content
      params {
        model
        temperature
        max_tokens
      }
      inputSchema
      createdAt
    }
    createdBy {
      id
      name
    }
  }
}

query

prompts(mine: Boolean, limit: Int)

List all prompts with optional filtering

Parameter	Type	Description
`mine`	`Boolean`	If true, only return prompts created by the current user
`limit`	`Int`	Maximum number of prompts to return (default: 50)

query GetMyPrompts {
  prompts(mine: true, limit: 20) {
    id
    name
    description
    category
    updatedAt
  }
}

query

chain(id: ID!)

Fetch a single chain with all steps and configuration

query GetChain($id: ID!) {
  chain(id: $id) {
    id
    name
    description
    isActive
    requiredInputs
    steps {
      id
      order
      type
      config
      inputMapping
      outputKey
      prompt {
        id
        name
      }
    }
  }
}

query

chains(mine: Boolean, limit: Int)

List all chains with optional filtering

query

executions

List execution history for prompts

query GetExecutions {
  executions {
    id
    status
    output
    error
    latencyMs
    tokenIn
    tokenOut
    costUsd
    createdAt
    promptVersion {
      prompt {
        name
      }
      version
    }
  }
}

Mutations

mutation

createPrompt

Create a new prompt (without content - use createPromptVersion to add content)

Parameter	Type	Description
`name` required	`String!`	Unique name for the prompt (will be converted to kebab-case)
`description`	`String`	Human-readable description of what the prompt does
`category`	`PromptCategory`	Category: GENERAL, SUMMARIZATION, ANALYSIS, GENERATION, etc.
`isPublic`	`Boolean`	Whether the prompt is publicly visible (default: false)

mutation CreatePrompt($input: CreatePromptInput!) {
  createPrompt(input: $input) {
    id
    name
    createdAt
  }
}

mutation

createPromptVersion

Create a new version of a prompt with content and configuration

Parameter	Type	Description
`promptId` required	`ID!`	ID of the prompt to add a version to
`content` required	`String!`	Template content with {{variable}} placeholders
`params` required	`ModelParams!`	Model configuration (model, temperature, max_tokens)
`inputSchema`	`JSON`	JSON Schema defining required input variables

mutation CreatePromptVersion($input: CreatePromptVersionInput!) {
  createPromptVersion(input: $input) {
    id
    version
    content
    params {
      model
      temperature
      max_tokens
    }
  }
}

mutation

executePrompt

Execute a prompt with the provided input variables

Parameter	Type	Description
`promptId` required	`ID!`	ID of the prompt to execute
`input` required	`JSON!`	Object containing values for all required variables

mutation ExecutePrompt($promptId: ID!, $input: JSON!) {
  executePrompt(promptId: $promptId, input: $input) {
    output
    latencyMs
    tokenIn
    tokenOut
    costUsd
    executionId
  }
}

mutation

createChain

Create a new multi-step workflow chain

mutation CreateChain($input: CreateChainInput!) {
  createChain(input: $input) {
    id
    name
    description
    isActive
  }
}

mutation

executeChain

Execute a chain workflow with input data

Parameter	Type	Description
`chainId` required	`ID!`	ID of the chain to execute
`input` required	`JSON!`	Input data matching the chain's required inputs schema

mutation ExecuteChain($chainId: ID!, $input: JSON!) {
  executeChain(chainId: $chainId, input: $input) {
    output
    steps {
      order
      type
      output
      latency
      cost
    }
    totalLatency
    totalCost
  }
}

mutation

routeMessage

Route a user message to the appropriate chain using keyword matching

mutation RouteMessage($input: RouteMessageInput!) {
  routeMessage(input: $input) {
    chain {
      id
      name
      description
    }
    intent
    extractedInputs
    rationale
  }
}

mutation

routeMessageSemantic

Route a user message using AI-powered semantic understanding

mutation RouteMessageSemantic($input: RouteMessageInput!) {
  routeMessageSemantic(input: $input) {
    chain {
      id
      name
      description
    }
    intent
    extractedInputs
    rationale
    clarifyingQuestion
  }
}

mutation

forkPrompt

Create a copy of an existing prompt with all versions

mutation ForkPrompt($id: ID!) {
  forkPrompt(id: $id) {
    id
    name
    versions {
      id
      version
    }
  }
}

Types

Prompt

type Prompt {
  id: ID!
  name: String!
  description: String
  category: PromptCategory
  isPublic: Boolean!
  versions: [PromptVersion!]!
  createdBy: User!
  createdAt: DateTime!
  updatedAt: DateTime!
}

PromptVersion

type PromptVersion {
  id: ID!
  version: Int!
  content: String!
  params: ModelParams!
  inputSchema: JSON
  createdAt: DateTime!
}

Chain

type Chain {
  id: ID!
  name: String!
  description: String
  isActive: Boolean!
  requiredInputs: JSON
  steps: [ChainStep!]!
  intentTags: [String!]
  createdBy: User!
  createdAt: DateTime!
  updatedAt: DateTime!
}

ChainStep

type ChainStep {
  id: ID!
  order: Int!
  type: StepType!
  config: JSON
  inputMapping: JSON
  outputKey: String
  prompt: Prompt
}

Execution

type Execution {
  id: ID!
  status: ExecutionStatus!
  output: String
  error: String
  latencyMs: Int
  tokenIn: Int
  tokenOut: Int
  costUsd: String
  createdAt: DateTime!
  promptVersion: PromptVersion!
  user: User!
}

Enums

PromptCategory

enum PromptCategory {
  GENERAL
  SUMMARIZATION
  ANALYSIS
  GENERATION
  CLASSIFICATION
  EXTRACTION
  ROUTING
  CUSTOM
}

StepType

enum StepType {
  PROMPT
  API_CALL
  CONDITION
  TRANSFORM
}

ExecutionStatus

enum ExecutionStatus {
  pending
  success
  error
}

For interactive API exploration, try using GraphiQL or GraphQL Playground pointing tohttps://api.promptforge.sh/graphql