Fragments API

Overview

The Fragments API manages reusable prompt components that can be composed into complete prompts. Fragments ensure consistency across agents and enable modular prompt engineering.

Base URL: https://api.so1.io/v1/veritas/fragments

Fragment Types

Type	Purpose	Example Use Case
role	Define expert personas	”You are a senior software engineer…“
constraints	Consistent guidelines	”Follow TypeScript best practices…“
examples	Few-shot learning	Code examples, output formats
context	Domain knowledge	API documentation, style guides
format	Output structure	JSON schemas, markdown templates

Create Fragment

Endpoint

POST /v1/veritas/fragments

Request Body

name

string

required

Unique fragment identifier

type

string

required

Fragment type: role, constraints, examples, context, format

content

string

required

Fragment text content

description

string

Fragment purpose and usage

metadata

object

Additional metadata (domain, tags, version)

Example Request

curl -X POST https://api.so1.io/v1/veritas/fragments \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "expert-backend-engineer",
    "type": "role",
    "content": "You are a senior backend engineer with 10+ years of experience in TypeScript, Node.js, and distributed systems. You write clean, maintainable code following SOLID principles.",
    "description": "Expert backend engineer persona for code generation",
    "metadata": {
      "domain": "engineering",
      "tags": ["backend", "typescript", "expert"],
      "version": "1.0.0"
    }
  }'

Response

{
  "success": true,
  "data": {
    "fragmentId": "expert-backend-engineer",
    "type": "role",
    "version": 1,
    "createdAt": "2024-03-10T15:30:00Z"
  }
}

Get Fragment

Endpoint

GET /v1/veritas/fragments/{fragmentId}

Response

{
  "success": true,
  "data": {
    "fragmentId": "expert-backend-engineer",
    "name": "Expert Backend Engineer",
    "type": "role",
    "content": "You are a senior backend engineer...",
    "description": "Expert backend engineer persona",
    "version": 1,
    "metadata": {
      "domain": "engineering",
      "tags": ["backend", "typescript", "expert"]
    },
    "usage": {
      "promptCount": 23,
      "chainCount": 7
    },
    "createdAt": "2024-03-10T15:30:00Z"
  }
}

List Fragments

Endpoint

GET /v1/veritas/fragments

Query Parameters

type

string

Filter by fragment type

domain

string

Filter by domain

tag

string

Filter by tag

limit

number

default:"20"

Results per page (1-100)

Response

{
  "success": true,
  "data": {
    "fragments": [
      {
        "fragmentId": "expert-backend-engineer",
        "name": "Expert Backend Engineer",
        "type": "role",
        "domain": "engineering",
        "usedInPrompts": 23,
        "createdAt": "2024-03-10T15:30:00Z"
      },
      {
        "fragmentId": "api-best-practices",
        "name": "API Best Practices",
        "type": "constraints",
        "domain": "engineering",
        "usedInPrompts": 18
      }
      // ... more fragments
    ],
    "pagination": {
      "total": 87,
      "limit": 20,
      "hasMore": true
    }
  }
}

Update Fragment

Endpoint

PUT /v1/veritas/fragments/{fragmentId}

Request Body

content

string

Updated content

description

string

Updated description

createNewVersion

boolean

default:"false"

Create new version vs. update current

Response

{
  "success": true,
  "data": {
    "fragmentId": "expert-backend-engineer",
    "version": 2,
    "updatedAt": "2024-03-10T16:00:00Z"
  }
}

Delete Fragment

Endpoint

DELETE /v1/veritas/fragments/{fragmentId}

Response

{
  "success": true,
  "data": {
    "fragmentId": "expert-backend-engineer",
    "deletedAt": "2024-03-10T16:00:00Z"
  }
}

Dependency Check: Deleting a fragment will fail if it’s used in active prompts. Remove fragment references first or use force=true query parameter.

Using Fragments in Prompts

Reference fragments in prompt templates using {{fragment:fragment-id}} syntax:

Example: Composing a Prompt from Fragments

const prompt = await client.veritas.prompts.create({
  name: 'api-endpoint-generator',
  template: `{{fragment:expert-backend-engineer}}

{{fragment:api-best-practices}}

Task: Generate a {{method}} endpoint for {{path}}

Description: {{description}}

{{fragment:hono-api-example}}

Provide complete, production-ready code.`,
  variables: ['method', 'path', 'description'],
  metadata: {
    fragments: [
      'expert-backend-engineer',
      'api-best-practices',
      'hono-api-example'
    ]
  }
});

When the prompt is executed, fragments are automatically resolved:

You are a senior backend engineer with 10+ years of experience...

Follow these API best practices:
- Use RESTful conventions
- Implement proper error handling
...

Task: Generate a POST endpoint for /api/users

Description: Create new user with email and name validation

[Example code from fragment]

Provide complete, production-ready code.

Fragment Collections

Group related fragments for domain-specific prompt engineering.

Example Collections

const backendFragments = [
  {
    name: 'expert-backend-engineer',
    type: 'role',
    content: 'You are a senior backend engineer...'
  },
  {
    name: 'backend-constraints',
    type: 'constraints',
    content: '- Use TypeScript strict mode\n- Implement error handling...'
  },
  {
    name: 'hono-example',
    type: 'examples',
    content: 'app.get("/api/users", async (c) => {...})'
  }
];

Common Patterns

Consistent Agent Behavior

Use role fragments to ensure consistent agent personas:

// All backend agents use the same role fragment
const backendAgentPrompts = [
  'api-endpoint-generator',
  'database-schema-designer',
  'api-documentation-generator'
].map(promptName => ({
  template: `{{fragment:expert-backend-engineer}}\n\n[specific task instructions]`
}));

Domain-Specific Constraints

Apply consistent guidelines across domain:

// All engineering prompts include these constraints
const engineeringConstraints = {
  name: 'engineering-standards',
  type: 'constraints',
  content: `- Follow TypeScript strict mode
- Implement comprehensive error handling
- Include JSDoc comments
- Write unit tests
- Follow SOLID principles`
};

Few-Shot Learning Examples

Provide consistent examples across similar tasks:

const apiExamples = {
  name: 'rest-api-examples',
  type: 'examples',
  content: `Example GET endpoint:
\`\`\`typescript
app.get("/api/users/:id", async (c) => {
  const id = c.req.param("id");
  const user = await db.user.findUnique({ where: { id } });
  return c.json(user);
});
\`\`\`

Example POST endpoint:
\`\`\`typescript
app.post("/api/users", async (c) => {
  const body = await c.req.json();
  const user = await db.user.create({ data: body });
  return c.json(user, 201);
});
\`\`\``
};

Fragment Versioning

Fragments support versioning for safe updates:

// Update fragment with new version
await client.veritas.fragments.update('expert-backend-engineer', {
  content: 'Enhanced role description...',
  createNewVersion: true // Creates v2, keeps v1 active
});

// Prompts using v1 continue unchanged
// New prompts get v2 by default
// Explicitly specify version:
const prompt = {
  template: `{{fragment:expert-backend-engineer:1}}\n\n[task]` // Use v1
};

Prompts API

Use fragments in prompts

Fragment Curator Agent

AI agent for managing fragments

Chains API

Multi-step prompt sequences

Veritas Overview

Veritas API introduction

API Reference

Control Plane API

Veritas API

n8n API

Overview

Fragment Types

Create Fragment

Endpoint

Request Body

Example Request

Response

Get Fragment

Endpoint

Response

List Fragments

Endpoint

Query Parameters

Response

Update Fragment

Endpoint

Request Body

Response

Delete Fragment

Endpoint

Response

Using Fragments in Prompts

Example: Composing a Prompt from Fragments

Fragment Collections

Example Collections

Common Patterns

Consistent Agent Behavior

Domain-Specific Constraints

Few-Shot Learning Examples

Fragment Versioning

Prompts API

Fragment Curator Agent

Chains API

Veritas Overview

API Reference

Control Plane API

Veritas API

n8n API

​Overview

​Fragment Types

​Create Fragment

​Endpoint

​Request Body

​Example Request

​Response

​Get Fragment

​Endpoint

​Response

​List Fragments

​Endpoint

​Query Parameters

​Response

​Update Fragment

​Endpoint

​Request Body

​Response

​Delete Fragment

​Endpoint

​Response

​Using Fragments in Prompts

​Example: Composing a Prompt from Fragments

​Fragment Collections

​Example Collections

​Common Patterns

​Consistent Agent Behavior

​Domain-Specific Constraints

​Few-Shot Learning Examples

​Fragment Versioning

​Related Resources

Prompts API

Fragment Curator Agent

Chains API

Veritas Overview

Overview

Fragment Types

Create Fragment

Endpoint

Request Body

Example Request

Response

Get Fragment

Endpoint

Response

List Fragments

Endpoint

Query Parameters

Response

Update Fragment

Endpoint

Request Body

Response

Delete Fragment

Endpoint

Response

Using Fragments in Prompts

Example: Composing a Prompt from Fragments

Fragment Collections

Example Collections

Common Patterns

Consistent Agent Behavior

Domain-Specific Constraints

Few-Shot Learning Examples

Fragment Versioning

Related Resources