Backend API Reference

Complete REST API documentation for PsicoStacks backend.

Base URL:

https://psicostacks-backend.vercel.app

Authentication

Most endpoints require a wallet address for identification. No API keys needed for public endpoints.

POST/api/ai-interpret

Upload and process a psychometric assessment PDF with AI analysis.

Request (multipart/form-data)

curl -X POST https://psicostacks-backend.vercel.app/api/ai-interpret \
  -F "file=@assessment.pdf" \
  -F "walletAddress=SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7"

Response (200 OK)

{
  "summary": {
    "band": "A",
    "bullets": [
      "High analytical thinking (92nd percentile)",
      "Strong problem-solving skills",
      "Excellent attention to detail"
    ],
    "note": "Outstanding cognitive abilities"
  },
  "fullReport": {
    "assessmentType": "Cognitive Assessment",
    "scores": { "verbal": 85, "numerical": 90, "abstract": 88 },
    "percentiles": { "verbal": 92, "numerical": 95, "abstract": 90 }
  }
}

POST/api/credentials

Save credential data after blockchain minting.

Request Body

{
  "walletAddress": "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7",
  "blockchainId": 22,
  "credentialData": {
    "summary": { ... },
    "fullReport": { ... }
  },
  "txId": "0xabc123..."
}

Response (201 Created)

{
  "credentialId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "createdAt": "2024-10-15T20:00:00Z"
}

GET/api/credentials

Get all credentials for a wallet address.

Query Parameters

Parameter	Required	Description
`walletAddress`	Yes	Stacks wallet address

Response (200 OK)

{
  "credentials": [
    {
      "id": "550e8400-...",
      "blockchain_id": 22,
      "wallet_address": "SP2J6Z...",
      "status": "active",
      "revoked": false,
      "created_at": "2024-10-15T20:00:00Z",
      "summary": { "band": "A", "bullets": [...] }
    }
  ]
}

POST/api/credentials/share

Generate a shareable verification link.

Request Body

{
  "credentialId": "550e8400-..."
}

Response (200 OK)

{
  "shareToken": "share_abc123def456",
  "shareUrl": "https://psicostacks.netlify.app/verify?token=share_...",
  "expiresAt": "2024-10-15T22:00:00Z"
}

POST/api/verify/preview

Get credential preview (free, no payment required).

Response (200 OK)

{
  "blockchain_id": 22,
  "wallet_address": "SP2J6Z...",
  "summary": {
    "band": "A",
    "bullets": ["High analytical thinking", "..."]
  }
}

POST/api/verify/pay

Generate view token after payment verification.

Request Body

{
  "shareToken": "share_abc123def456",
  "txId": "0xabc123...",
  "blockchainId": 22,
  "employerWallet": "SP3K8BC..."
}

Response (200 OK)

{
  "viewUrl": "https://psicostacks.netlify.app/verify/view?token=view_xyz789",
  "expiresAt": "2024-10-15T20:01:00Z"
}

Error Codes

Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid credentials
404	Not Found - Resource doesn't exist
409	Conflict - Already revoked/expired
500	Internal Server Error

Related Resources

→ View Backend Repository → Smart Contract API → Understand the Flow