Prompt Management API (MVP)

This document describes the primary APIs used by the Prompt Repository UI.

Projects & Repositories

• GET /api/v1/projects
  • Returns projects the user can access.
• GET /api/v1/projects/{projectId}/repositories
  • Returns repositories within a project.
• GET /api/v1/repositories/{repositoryId}/prompts
  • List prompts in a repository; supports query params: branch, category, tags, search, limit, offset.
  • Lists only prompts you can see, the same as GET /api/v1/prompts: your own, public ones, and ones shared with you or your team. Admins see every prompt in the repository.
• POST /api/v1/repositories/{repositoryId}/prompts

  • Create a client-encrypted (zero-knowledge) prompt in a repository.

  • Body: { name, encryptedPayload: { userPrompt: { alg, iv, ct, tag? }, systemPrompt? }, promptHash, encryptionKeyId, keyVersion, tags?, category? }. A request without encryptedPayload returns 400.

  • For a plaintext prompt, call POST /api/v1/prompts with the repository's public id instead (the prompt repository page does this):

    curl -X POST "https://app.veriprompt.tech/api/v1/prompts" \
      -H "Content-Type: application/json" -b "<session cookie>" \
      -d '{"name": "Ticket triage", "userPrompt": "Classify this ticket: {{ticket}}", "repositoryId": "repo_3f9c1a2b4d5e6f70"}'

    repositoryId is the public id (repo_…) returned by GET /api/v1/projects/{projectId}/repositories, not the internal id. If the repository requires zero-knowledge encryption, the plaintext create returns 400.

  • Both create calls need write access to the repository: a repository role with prompt:create (directly or through the project), or account owner/admin. Otherwise they return 403. The repository's prompt list reports this as permissions.canWrite.

• PUT /api/v1/projects/{projectId}
  • Update project metadata and compliance settings.
  • Fields (all optional): name, description, keywords, notes, geoFenceRules, allowPromptGeoOverrides
  • geoFenceRules shape:

    {
      "allow": {
        "countries": ["US", "DE"],
        "memberships": ["GDPR"],
        "networks": ["AMS", "SJC"]
      },
      "deny": {
        "countries": ["CN"],
        "memberships": ["ITAR"],
        "networks": ["BOM"]
      }
    }

  • Set geoFenceRules to null to clear project-level restrictions. Toggle allowPromptGeoOverrides to permit prompt-level overrides.

Prompt Detail & Update

• GET /api/v1/prompts/{promptId}
  • Returns prompt details, versions, and recent executions summary.
• PUT /api/v1/prompts/{promptId}
  • Fields (all optional):
    • name, description, systemPrompt, userPrompt, temperature, maxTokens, stopSequences, tags, category, isActive, metadata
    • routingPolicyId: set default Routing Policy for Quick Tests
    • geoFenceRules: prompt-level override for geofencing (same schema as project rules). Use null to revert to project defaults.
    • attachment (single “current” attachment; no versioning):
      • Text: { "type": "text", "content": "..." }
      • URL: { "type": "url", "url": "https://..." }
      • File: { "type": "file", "fileId": "...", "fileName": "...", "fileType": "...", "fileSize": 12345 }
  • Response includes geoFenceRules on the prompt plus { allowPromptGeoOverrides, geoFenceRules } under repository.project for UI inheritance decisions.

Attachments (File Upload)

• GET /api/v1/files/upload
  • Returns upload limits (max size, allowed types).
• POST /api/v1/files/upload?processContent=true&category=prompt-attachment
  • Multipart: file
  • Response includes file.id, fileName, mimeType, and processing.extractedText if available.

Provider Groups & Routing Policies

• Provider Groups
  • GET /api/v1/providers/groups — list groups
  • POST /api/v1/providers/groups — create group
  • GET /api/v1/providers/groups/{id} — fetch
  • PATCH /api/v1/providers/groups/{id} — update
  • DELETE /api/v1/providers/groups/{id} — delete
  • Shape: { name, category, description?, region?, country?, pricingCluster?, members: [{ provider, model }] }
• Routing Policies
  • GET /api/v1/routing/policies
  • POST /api/v1/routing/policies
  • GET /api/v1/routing/policies/{id}
  • PATCH /api/v1/routing/policies/{id}
  • DELETE /api/v1/routing/policies/{id}
  • Policy JSON: routingPolicyV1 — includes hardConstraints, preferences.weights, logic.

Prompt Chaining (References)

• GET /api/v1/prompts/{promptId}/references
  • Returns list of prompts that reference this prompt (Referenced By).
  • Response: { referencedBy: [{ id, promptId, name, referenceSyntax, hasAccess, isCircular }], count }
• POST /api/v1/prompts/{promptId}/references
  • Validate and update references in a prompt.
  • Body: { promptText: string }
  • Response: { success, references: [{ promptId, hasAccess, isCircular, referenceSyntax, reason? }], errors: string[], hasErrors }
• PUT /api/v1/prompts/{promptId}/references/validate
  • Validate a specific reference.
  • Body: { targetPromptId: string }
  • Response: { hasAccess, isCircular?, circularPath?, targetPrompt?, reason? }

Syntax

• Shorthand: [promptID] - Converted to full syntax on blur if prompt exists
• Full syntax: {{prompt:promptID}} - Used for execution
• Error syntax: {{error:promptID - reason}} - Shown when reference is invalid

Reference Resolution

Prompts can reference other prompts using the syntax above. References are:

• Validated at creation: Access rights checked when [promptID] is inserted
• Validated at execution: Access re-checked before prompt execution
• Scope-aware: Admin configures COMPANY or PROJECT-level access per prompt
• Circular detection: System detects and warns about circular references
• Displayed in UI: "Referenced By" section shows where a prompt is used

Gateway – Execute

• POST /api/gateway/execute
  • Minimal body for default routing:

    {
      "prompt": "...",
      "systemPrompt": "...",
      "policyId": "<optional>",
      "providerGroupId": "<optional>",
      "attachments": [ {"type":"text","content":"..."}, {"type":"url","url":"..."} ],
      "resolveReferences": true,
      "maxTokens": 1000,
      "temperature": 0.7,
      "metadata": {"promptId":"..."}
    }

  • Prompt Chaining: Set resolveReferences: true to resolve {{prompt:id}} references before execution. Requires metadata.promptId to identify source prompt. Response includes referenceWarnings if any links fail validation.
  • Behavior: dynamic ranking + ROUND_ROBIN among top candidates when providerType is not provided.
  • Geofencing: when metadata.promptId or metadata.projectId is supplied, the gateway enforces project/prompt geoFenceRules. The response metadata includes geoRuleSource and geoRulesApplied, and execution metrics now expose routingMetrics.geo.ruleSource to audit effective routing.

---

This API surface is stable for MVP and will expand (e.g., approval flows, richer diffs, side‑by‑side exports).