> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Attestation

> Create a new trust attestation for a subject

## Overview

Create a new trust attestation that provides verifiable proof of a relationship, skill, or attribute. This endpoint allows users to issue attestations that can be used for trust scoring, reputation building, and identity verification.

<Tip>
  Use this endpoint to create verifiable attestations that can be used for trust scoring, reputation systems, and identity verification. Attestations are cryptographically signed and immutable.
</Tip>

## Parameters

<ParamField body="subject" type="string" required>
  The identity being attested to (ZKS ID or wallet address)
</ParamField>

<ParamField body="schema" type="string" required>
  The attestation schema identifier

  * `skill` - Skill or expertise attestation
  * `relationship` - Relationship attestation
  * `achievement` - Achievement attestation
  * `reputation` - Reputation attestation
  * `identity` - Identity verification attestation
  * `custom` - Custom schema
</ParamField>

<ParamField body="data" type="object" required>
  Attestation data payload

  <Expandable title="data properties">
    <ParamField body="data.title" type="string">
      Attestation title
    </ParamField>

    <ParamField body="data.description" type="string">
      Attestation description
    </ParamField>

    <ParamField body="data.category" type="string">
      Attestation category
    </ParamField>

    <ParamField body="data.value" type="string">
      Attestation value or score
    </ParamField>

    <ParamField body="data.metadata" type="object">
      Additional metadata
    </ParamField>

    <ParamField body="data.evidence" type="array">
      Supporting evidence

      <Expandable title="evidence properties">
        <ParamField body="data.evidence[].type" type="string">
          Evidence type (url, document, transaction, etc.)
        </ParamField>

        <ParamField body="data.evidence[].value" type="string">
          Evidence value
        </ParamField>

        <ParamField body="data.evidence[].description" type="string">
          Evidence description
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="signature" type="string" required>
  Cryptographic signature of the attestation
</ParamField>

<ParamField body="expiry" type="string">
  ISO 8601 timestamp when attestation expires (optional)
</ParamField>

<ParamField body="revocable" type="boolean">
  Whether the attestation can be revoked (default: true)
</ParamField>

<ParamField body="public" type="boolean">
  Whether the attestation is publicly visible (default: true)
</ParamField>

<ParamField body="tags" type="array">
  Tags for categorization and discovery
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the attestation was created successfully
</ResponseField>

<ResponseField name="attestationId" type="string">
  Unique identifier of the created attestation
</ResponseField>

<ResponseField name="attestation" type="object">
  Created attestation details

  <Expandable title="attestation properties">
    <ResponseField name="id" type="string">
      Attestation identifier
    </ResponseField>

    <ResponseField name="subject" type="string">
      Attested identity
    </ResponseField>

    <ResponseField name="issuer" type="string">
      Attestation issuer
    </ResponseField>

    <ResponseField name="schema" type="string">
      Attestation schema
    </ResponseField>

    <ResponseField name="data" type="object">
      Attestation data
    </ResponseField>

    <ResponseField name="signature" type="string">
      Attestation signature
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="expiry" type="string">
      ISO 8601 timestamp of expiry (if set)
    </ResponseField>

    <ResponseField name="revocable" type="boolean">
      Whether attestation can be revoked
    </ResponseField>

    <ResponseField name="public" type="boolean">
      Whether attestation is publicly visible
    </ResponseField>

    <ResponseField name="status" type="string">
      Attestation status (active, expired, revoked)
    </ResponseField>

    <ResponseField name="tags" type="array">
      Attestation tags
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="verification" type="object">
  Attestation verification details

  <Expandable title="verification properties">
    <ResponseField name="verified" type="boolean">
      Whether attestation is verified
    </ResponseField>

    <ResponseField name="verificationMethod" type="string">
      Method used for verification
    </ResponseField>

    <ResponseField name="verificationTimestamp" type="string">
      ISO 8601 timestamp of verification
    </ResponseField>

    <ResponseField name="trustScore" type="number">
      Trust score of the attestation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of the response
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL (Skill Attestation) theme={null}
  curl -X POST "https://api.onzks.com/v1/trust/attestations" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "subject": "alice.zks",
      "schema": "skill",
      "data": {
        "title": "Solidity Developer",
        "description": "Expert in smart contract development",
        "category": "programming",
        "value": "expert",
        "metadata": {
          "yearsExperience": 5,
          "projects": ["DeFi Protocol", "NFT Marketplace"],
          "certifications": ["Certified Solidity Developer"]
        },
        "evidence": [
          {
            "type": "url",
            "value": "https://github.com/alice/solidity-projects",
            "description": "GitHub repository with Solidity projects"
          },
          {
            "type": "document",
            "value": "certificate.pdf",
            "description": "Certification document"
          }
        ]
      },
      "signature": "0xabcdef1234567890...",
      "expiry": "2025-01-20T15:45:00Z",
      "revocable": true,
      "public": true,
      "tags": ["solidity", "blockchain", "developer"]
    }'
  ```

  ```bash cURL (Relationship Attestation) theme={null}
  curl -X POST "https://api.onzks.com/v1/trust/attestations" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "subject": "bob.zks",
      "schema": "relationship",
      "data": {
        "title": "Business Partner",
        "description": "Long-term business partnership",
        "category": "business",
        "value": "trusted",
        "metadata": {
          "relationshipType": "business_partner",
          "duration": "3 years",
          "projects": ["Joint Venture", "Consulting"]
        },
        "evidence": [
          {
            "type": "transaction",
            "value": "0x1234567890abcdef...",
            "description": "Business transaction history"
          }
        ]
      },
      "signature": "0x1234567890abcdef...",
      "revocable": true,
      "public": true,
      "tags": ["business", "partnership", "trusted"]
    }'
  ```

  ```bash cURL (Achievement Attestation) theme={null}
  curl -X POST "https://api.onzks.com/v1/trust/attestations" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "subject": "charlie.zks",
      "schema": "achievement",
      "data": {
        "title": "DeFi Protocol Launch",
        "description": "Successfully launched a DeFi protocol",
        "category": "achievement",
        "value": "completed",
        "metadata": {
          "protocolName": "YieldFarm Protocol",
          "launchDate": "2024-01-15",
          "totalValueLocked": "1000000",
          "users": 500
        },
        "evidence": [
          {
            "type": "url",
            "value": "https://yieldfarm.xyz",
            "description": "Protocol website"
          },
          {
            "type": "transaction",
            "value": "0xabcdef1234567890...",
            "description": "Protocol deployment transaction"
          }
        ]
      },
      "signature": "0x9876543210fedcba...",
      "revocable": false,
      "public": true,
      "tags": ["defi", "protocol", "launch", "achievement"]
    }'
  ```

  ```javascript JavaScript theme={null}
  async function createAttestation(attestationData) {
    const {
      subject,
      schema,
      data,
      signature,
      expiry,
      revocable = true,
      public: isPublic = true,
      tags = []
    } = attestationData;

    const requestBody = {
      subject,
      schema,
      data,
      signature,
      revocable,
      public: isPublic,
      tags
    };

    if (expiry) {
      requestBody.expiry = expiry;
    }

    const response = await fetch('https://api.onzks.com/v1/trust/attestations', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(requestBody)
    });

    const result = await response.json();

    if (result.success) {
      console.log(`✅ Attestation created: ${result.attestationId}`);
      console.log(`Subject: ${result.attestation.subject}`);
      console.log(`Schema: ${result.attestation.schema}`);
      console.log(`Status: ${result.attestation.status}`);
      console.log(`Verified: ${result.verification.verified}`);
    } else {
      console.error('Failed to create attestation:', result.message);
    }

    return result;
  }

  // Usage examples
  await createAttestation({
    subject: 'alice.zks',
    schema: 'skill',
    data: {
      title: 'Solidity Developer',
      description: 'Expert in smart contract development',
      category: 'programming',
      value: 'expert',
      metadata: {
        yearsExperience: 5,
        projects: ['DeFi Protocol', 'NFT Marketplace']
      },
      evidence: [
        {
          type: 'url',
          value: 'https://github.com/alice/solidity-projects',
          description: 'GitHub repository with Solidity projects'
        }
      ]
    },
    signature: '0xabcdef1234567890...',
    tags: ['solidity', 'blockchain', 'developer']
  });
  ```

  ```python Python theme={null}
  import requests
  import json

  def create_attestation(subject, schema, data, signature, expiry=None, revocable=True, public=True, tags=None):
      if tags is None:
          tags = []
      
      request_body = {
          'subject': subject,
          'schema': schema,
          'data': data,
          'signature': signature,
          'revocable': revocable,
          'public': public,
          'tags': tags
      }
      
      if expiry:
          request_body['expiry'] = expiry
      
      response = requests.post(
          'https://api.onzks.com/v1/trust/attestations',
          headers={
              'Authorization': 'Bearer YOUR_API_KEY',
              'Content-Type': 'application/json'
          },
          json=request_body
      )
      
      result = response.json()
      
      if result['success']:
          print(f"✅ Attestation created: {result['attestationId']}")
          print(f"Subject: {result['attestation']['subject']}")
          print(f"Schema: {result['attestation']['schema']}")
          print(f"Status: {result['attestation']['status']}")
          print(f"Verified: {result['verification']['verified']}")
      else:
          print(f"Failed to create attestation: {result['message']}")
      
      return result

  # Usage examples
  create_attestation(
      subject='alice.zks',
      schema='skill',
      data={
          'title': 'Solidity Developer',
          'description': 'Expert in smart contract development',
          'category': 'programming',
          'value': 'expert',
          'metadata': {
              'yearsExperience': 5,
              'projects': ['DeFi Protocol', 'NFT Marketplace']
          },
          'evidence': [
              {
                  'type': 'url',
                  'value': 'https://github.com/alice/solidity-projects',
                  'description': 'GitHub repository with Solidity projects'
              }
          ]
      },
      signature='0xabcdef1234567890...',
      tags=['solidity', 'blockchain', 'developer']
  )
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "attestationId": "att_1234567890abcdef",
  "attestation": {
    "id": "att_1234567890abcdef",
    "subject": "alice.zks",
    "issuer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "schema": "skill",
    "data": {
      "title": "Solidity Developer",
      "description": "Expert in smart contract development",
      "category": "programming",
      "value": "expert",
      "metadata": {
        "yearsExperience": 5,
        "projects": ["DeFi Protocol", "NFT Marketplace"],
        "certifications": ["Certified Solidity Developer"]
      },
      "evidence": [
        {
          "type": "url",
          "value": "https://github.com/alice/solidity-projects",
          "description": "GitHub repository with Solidity projects"
        },
        {
          "type": "document",
          "value": "certificate.pdf",
          "description": "Certification document"
        }
      ]
    },
    "signature": "0xabcdef1234567890...",
    "createdAt": "2024-01-20T15:45:00Z",
    "expiry": "2025-01-20T15:45:00Z",
    "revocable": true,
    "public": true,
    "status": "active",
    "tags": ["solidity", "blockchain", "developer"]
  },
  "verification": {
    "verified": true,
    "verificationMethod": "signature_verification",
    "verificationTimestamp": "2024-01-20T15:45:00Z",
    "trustScore": 85.5
  },
  "timestamp": "2024-01-20T15:45:00Z"
}
```

## Use Cases

### 1. Skill Attestation System

Create a skill attestation system:

```javascript theme={null}
async function createSkillAttestation(subject, skill, evidence) {
  const attestationData = {
    subject,
    schema: 'skill',
    data: {
      title: skill.name,
      description: skill.description,
      category: skill.category,
      value: skill.level,
      metadata: {
        yearsExperience: skill.experience,
        projects: skill.projects,
        certifications: skill.certifications
      },
      evidence: evidence.map(ev => ({
        type: ev.type,
        value: ev.value,
        description: ev.description
      }))
    },
    signature: await signAttestation(subject, skill),
    tags: skill.tags
  };

  return await createAttestation(attestationData);
}

// Usage
const skill = {
  name: 'React Developer',
  description: 'Expert in React and frontend development',
  category: 'programming',
  level: 'expert',
  experience: 3,
  projects: ['E-commerce Platform', 'Dashboard App'],
  certifications: ['React Certification'],
  tags: ['react', 'javascript', 'frontend']
};

const evidence = [
  {
    type: 'url',
    value: 'https://github.com/alice/react-projects',
    description: 'GitHub repository with React projects'
  }
];

await createSkillAttestation('alice.zks', skill, evidence);
```

### 2. Relationship Attestation

Create relationship attestations:

```javascript theme={null}
async function createRelationshipAttestation(subject, relationship) {
  const attestationData = {
    subject,
    schema: 'relationship',
    data: {
      title: relationship.title,
      description: relationship.description,
      category: relationship.category,
      value: relationship.trustLevel,
      metadata: {
        relationshipType: relationship.type,
        duration: relationship.duration,
        projects: relationship.projects
      },
      evidence: relationship.evidence
    },
    signature: await signAttestation(subject, relationship),
    tags: relationship.tags
  };

  return await createAttestation(attestationData);
}

// Usage
const relationship = {
  title: 'Business Partner',
  description: 'Long-term business partnership',
  category: 'business',
  trustLevel: 'trusted',
  type: 'business_partner',
  duration: '3 years',
  projects: ['Joint Venture', 'Consulting'],
  evidence: [
    {
      type: 'transaction',
      value: '0x1234567890abcdef...',
      description: 'Business transaction history'
    }
  ],
  tags: ['business', 'partnership', 'trusted']
};

await createRelationshipAttestation('bob.zks', relationship);
```

### 3. Achievement Attestation

Create achievement attestations:

```javascript theme={null}
async function createAchievementAttestation(subject, achievement) {
  const attestationData = {
    subject,
    schema: 'achievement',
    data: {
      title: achievement.title,
      description: achievement.description,
      category: achievement.category,
      value: achievement.status,
      metadata: {
        completionDate: achievement.completionDate,
        metrics: achievement.metrics,
        impact: achievement.impact
      },
      evidence: achievement.evidence
    },
    signature: await signAttestation(subject, achievement),
    revocable: false, // Achievements are typically not revocable
    tags: achievement.tags
  };

  return await createAttestation(attestationData);
}

// Usage
const achievement = {
  title: 'DeFi Protocol Launch',
  description: 'Successfully launched a DeFi protocol',
  category: 'achievement',
  status: 'completed',
  completionDate: '2024-01-15',
  metrics: {
    totalValueLocked: '1000000',
    users: 500,
    transactions: 10000
  },
  impact: 'High',
  evidence: [
    {
      type: 'url',
      value: 'https://yieldfarm.xyz',
      description: 'Protocol website'
    },
    {
      type: 'transaction',
      value: '0xabcdef1234567890...',
      description: 'Protocol deployment transaction'
    }
  ],
  tags: ['defi', 'protocol', 'launch', 'achievement']
};

await createAchievementAttestation('charlie.zks', achievement);
```

### 4. Batch Attestation Creation

Create multiple attestations at once:

```javascript theme={null}
async function createBatchAttestations(attestations) {
  const results = [];
  
  for (const attestation of attestations) {
    try {
      const result = await createAttestation(attestation);
      results.push({ success: true, result });
    } catch (error) {
      results.push({ success: false, error: error.message });
    }
  }
  
  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);
  
  console.log(`Successfully created ${successful.length} attestations`);
  if (failed.length > 0) {
    console.log(`Failed to create ${failed.length} attestations`);
  }
  
  return results;
}
```

### 5. Attestation Templates

Use predefined templates:

```javascript theme={null}
const attestationTemplates = {
  skill: {
    schema: 'skill',
    requiredFields: ['title', 'description', 'category', 'value'],
    optionalFields: ['metadata', 'evidence'],
    defaultTags: ['skill', 'attestation']
  },
  relationship: {
    schema: 'relationship',
    requiredFields: ['title', 'description', 'category', 'value'],
    optionalFields: ['metadata', 'evidence'],
    defaultTags: ['relationship', 'attestation']
  },
  achievement: {
    schema: 'achievement',
    requiredFields: ['title', 'description', 'category', 'value'],
    optionalFields: ['metadata', 'evidence'],
    defaultTags: ['achievement', 'attestation']
  }
};

function createAttestationFromTemplate(template, data) {
  const templateConfig = attestationTemplates[template];
  
  if (!templateConfig) {
    throw new Error(`Unknown template: ${template}`);
  }
  
  // Validate required fields
  for (const field of templateConfig.requiredFields) {
    if (!data[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }
  
  return {
    schema: templateConfig.schema,
    data: {
      ...data,
      tags: [...(data.tags || []), ...templateConfig.defaultTags]
    }
  };
}
```

## Best Practices

### 1. Signature Verification

Always verify signatures before creating attestations:

```javascript theme={null}
async function verifyAttestationSignature(attestation, signature) {
  const message = JSON.stringify(attestation);
  const recoveredAddress = await recoverAddress(message, signature);
  
  return recoveredAddress === attestation.issuer;
}
```

### 2. Evidence Validation

Validate evidence before creating attestations:

```javascript theme={null}
function validateEvidence(evidence) {
  const validTypes = ['url', 'document', 'transaction', 'image', 'video'];
  
  return evidence.every(ev => {
    return validTypes.includes(ev.type) && 
           ev.value && 
           ev.description;
  });
}
```

### 3. Expiry Management

Handle attestation expiry:

```javascript theme={null}
function checkAttestationExpiry(attestation) {
  if (!attestation.expiry) {
    return { expired: false, daysRemaining: null };
  }
  
  const expiryDate = new Date(attestation.expiry);
  const now = new Date();
  const daysRemaining = Math.ceil((expiryDate - now) / (1000 * 60 * 60 * 24));
  
  return {
    expired: now > expiryDate,
    daysRemaining: daysRemaining > 0 ? daysRemaining : 0
  };
}
```

### 4. Privacy Controls

Implement privacy controls:

```javascript theme={null}
function createPrivateAttestation(attestationData) {
  return {
    ...attestationData,
    public: false,
    tags: [...(attestationData.tags || []), 'private']
  };
}

function createPublicAttestation(attestationData) {
  return {
    ...attestationData,
    public: true,
    tags: [...(attestationData.tags || []), 'public']
  };
}
```

## Related Endpoints

* [Get Attestations](/api-reference/trust-layer/get-attestations) - Retrieve attestations
* [Revoke Attestation](/api-reference/trust-layer/revoke-attestation) - Revoke an attestation
* [Evaluate Policy](/api-reference/trust-layer/evaluate-policy) - Evaluate trust policies
* [Get Modules](/api-reference/trust-layer/get-modules) - Get available trust modules

## Troubleshooting

### "Invalid signature"

**Cause**: The signature doesn't match the attestation data.

**Solution**:

* Verify the signature is correctly generated
* Ensure the message being signed matches the attestation data
* Check that the correct private key is being used

### "Invalid schema"

**Cause**: Unsupported schema identifier.

**Solution**:

* Use supported schemas: skill, relationship, achievement, reputation, identity, custom
* Check for typos in the schema name

### "Missing required fields"

**Cause**: Required fields are missing from the attestation data.

**Solution**:

* Include all required fields for the schema
* Check the schema documentation for required fields
* Validate the data structure before submission

### "Attestation already exists"

**Cause**: An identical attestation already exists.

**Solution**:

* Check if the attestation already exists
* Modify the attestation data to make it unique
* Consider updating the existing attestation instead

## Rate Limits

Attestation creation requests are subject to rate limits:

* **Free tier**: 10 attestations per minute
* **Starter tier**: 50 attestations per minute
* **Professional tier**: 200 attestations per minute
* **Enterprise tier**: Custom limits

Implement queuing for batch attestation creation to avoid rate limits.