{"openapi":"3.1.0","info":{"title":"PDF Cert Generator API","description":"**API-first PDF certificate generation.**\n\nGenerate tamper-proof participation and VTU-style internship completion certificates as downloadable PDFs with shareable URLs. All certificate data is encoded in the URL itself — signed with HMAC-SHA256, cryptographically verifiable without a database.\n\n## Authentication\n- **Certificate creation:** `X-API-Key` header (if `CERT_API_KEYS` is configured)\n- **Admin endpoints:** `X-Admin-Key` header\n- **Public endpoints:** No auth required (view, download, verify)\n\n## Agent / Automation Integration\n- OpenAPI spec: `GET /openapi.json`\n- Agent discovery: `GET /llms.txt`\n- Webhook callbacks: pass `callback_url` to receive async notifications\n- Idempotency: pass `idempotency_key` to prevent duplicate certificates\n- Batch verification: `POST /api/certificates/verify`\n","version":"2.0.0"},"paths":{"/":{"get":{"tags":["System"],"summary":"Root","description":"API root with version and available endpoints.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/health":{"get":{"tags":["System"],"summary":"Health Check","description":"Health check. Returns 200 if the service is running.","operationId":"health_check_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/info":{"get":{"tags":["System"],"summary":"Get Info","description":"API metadata including version, features, branding, and tech stack.","operationId":"get_info_api_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/preview/qr":{"get":{"tags":["System"],"summary":"Preview Qr","description":"Generate a QR code data URI for UI previews (does not create credentials).","operationId":"preview_qr_api_preview_qr_get","parameters":[{"name":"url","in":"query","required":false,"schema":{"type":"string","default":"","title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/courses":{"get":{"tags":["Courses"],"summary":"Get Courses","description":"List all active courses available for certificate generation.","operationId":"get_courses_api_courses_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/certificate":{"post":{"tags":["Certificates"],"summary":"Generate Certificate","description":"Generate a signed certificate and return shareable URL + PDF download URL.\n\n**Participation (default):** `certificate_kind` omitted or `\"participation\"` — standard course certificate.\n\n**Internship (VTU / college records):** set `certificate_kind` to `\"internship\"` and include\n`usn`, `internship_duration`, `internship_hours`, and `mentor_name` (plus optional `institution_name`).\n\n**Appreciation (sports / events):** set `certificate_kind` to `\"appreciation\"` with\n`recognition_text` (or `venue_name` for auto-generated copy), plus optional `event_name`,\n`sponsor_label`, and `venue_name`. Course list validation is skipped; PDF uses the landscape\nappreciation layout with verifiable QR.\n\n**Idempotency:** Pass `idempotency_key` to safely retry without creating duplicates.\nThe cached result is returned for 1 hour.\n\n**Webhook:** Pass `callback_url` to receive an async POST with the certificate data\nafter creation. Useful for automation pipelines.\n\n**Email:** Pass `participant_email` to automatically email the certificate to the participant.","operationId":"generate_certificate_api_certificate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/invoice":{"post":{"tags":["Invoices"],"summary":"Generate Invoice","description":"Generate a signed tax invoice and return shareable download URL + totals.\n\nLine items are priced in USD; INR total uses `exchange_rate` (default 90).\nPass `idempotency_key` to safely retry without creating duplicate tokens.","operationId":"generate_invoice_api_invoice_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/invoice/{token}/download":{"get":{"tags":["Invoices"],"summary":"Download Invoice","description":"Download a tax invoice PDF from a signed token.","operationId":"download_invoice_invoice__token__download_get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/certificate/{token}/download":{"get":{"tags":["Certificates"],"summary":"Download Certificate","description":"Download a certificate. Appreciation certs open the viewer print dialog (WYSIWYG PDF).","operationId":"download_certificate_certificate__token__download_get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/certificate/{token}/verify":{"get":{"tags":["Verification"],"summary":"Verify Certificate","description":"Verify a single certificate's authenticity by its token. Returns the decoded certificate data if valid.","operationId":"verify_certificate_certificate__token__verify_get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/certificates/verify":{"post":{"tags":["Verification"],"summary":"Batch Verify Certificates","description":"Verify multiple certificates in a single request.\nAccepts up to 100 tokens. Returns verification result for each.","operationId":"batch_verify_certificates_api_certificates_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchVerifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/stats":{"get":{"tags":["Admin"],"summary":"Admin Stats","description":"Get certificate analytics: total, weekly, revoked counts and per-course breakdown.","operationId":"admin_stats_api_admin_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/admin/certificates":{"get":{"tags":["Admin"],"summary":"Admin List Certificates","operationId":"admin_list_certificates_api_admin_certificates_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"course","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Course"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/certificates/{cert_db_id}/revoke":{"post":{"tags":["Admin"],"summary":"Admin Revoke Certificate","operationId":"admin_revoke_certificate_api_admin_certificates__cert_db_id__revoke_post","parameters":[{"name":"cert_db_id","in":"path","required":true,"schema":{"type":"integer","title":"Cert Db Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/certificates/bulk":{"post":{"tags":["Admin"],"summary":"Admin Bulk Generate","description":"Generate up to 500 certificates in a single request. Each entry is validated independently.","operationId":"admin_bulk_generate_api_admin_certificates_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCertificateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/courses":{"get":{"tags":["Admin"],"summary":"Admin List Courses","operationId":"admin_list_courses_api_admin_courses_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["Admin"],"summary":"Admin Add Course","operationId":"admin_add_course_api_admin_courses_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/courses/{course_id}":{"patch":{"tags":["Admin"],"summary":"Admin Toggle Course","operationId":"admin_toggle_course_api_admin_courses__course_id__patch","parameters":[{"name":"course_id","in":"path","required":true,"schema":{"type":"integer","title":"Course Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseToggleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BatchVerifyRequest":{"properties":{"tokens":{"items":{"type":"string"},"type":"array","title":"Tokens"}},"type":"object","required":["tokens"],"title":"BatchVerifyRequest"},"BulkCertificateEntry":{"properties":{"participant_name":{"type":"string","title":"Participant Name"},"course_name":{"type":"string","title":"Course Name","default":""},"completion_date":{"type":"string","title":"Completion Date"},"instructor_name":{"type":"string","title":"Instructor Name","default":"Certificate Team"},"participant_email":{"type":"string","title":"Participant Email","default":""},"certificate_kind":{"type":"string","enum":["participation","internship","appreciation"],"title":"Certificate Kind","default":"participation"},"usn":{"type":"string","title":"Usn","default":""},"internship_duration":{"type":"string","title":"Internship Duration","default":""},"internship_hours":{"type":"string","title":"Internship Hours","default":""},"mentor_name":{"type":"string","title":"Mentor Name","default":""},"institution_name":{"type":"string","title":"Institution Name","default":""},"recognition_text":{"type":"string","title":"Recognition Text","default":""},"event_name":{"type":"string","title":"Event Name","default":""},"venue_name":{"type":"string","title":"Venue Name","default":""},"sponsor_label":{"type":"string","title":"Sponsor Label","default":""}},"type":"object","required":["participant_name","completion_date"],"title":"BulkCertificateEntry"},"BulkCertificateRequest":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/BulkCertificateEntry"},"type":"array","title":"Entries"}},"type":"object","required":["entries"],"title":"BulkCertificateRequest"},"CertificateRequest":{"properties":{"participant_name":{"type":"string","title":"Participant Name"},"course_name":{"type":"string","title":"Course Name","default":""},"completion_date":{"type":"string","title":"Completion Date"},"instructor_name":{"type":"string","title":"Instructor Name","default":"Certificate Team"},"participant_email":{"type":"string","title":"Participant Email","default":""},"callback_url":{"type":"string","title":"Callback Url","default":""},"idempotency_key":{"type":"string","title":"Idempotency Key","default":""},"certificate_kind":{"type":"string","enum":["participation","internship","appreciation"],"title":"Certificate Kind","default":"participation"},"usn":{"type":"string","title":"Usn","default":""},"internship_duration":{"type":"string","title":"Internship Duration","default":""},"internship_hours":{"type":"string","title":"Internship Hours","default":""},"mentor_name":{"type":"string","title":"Mentor Name","default":""},"institution_name":{"type":"string","title":"Institution Name","default":""},"recognition_text":{"type":"string","title":"Recognition Text","default":""},"event_name":{"type":"string","title":"Event Name","default":""},"venue_name":{"type":"string","title":"Venue Name","default":""},"sponsor_label":{"type":"string","title":"Sponsor Label","default":""}},"type":"object","required":["participant_name","completion_date"],"title":"CertificateRequest"},"CourseCreateRequest":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""}},"type":"object","required":["name"],"title":"CourseCreateRequest"},"CourseToggleRequest":{"properties":{"active":{"type":"boolean","title":"Active"}},"type":"object","required":["active"],"title":"CourseToggleRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InvoiceLineItemRequest":{"properties":{"description":{"type":"string","title":"Description"},"rate":{"type":"number","title":"Rate"},"rate_label":{"type":"string","title":"Rate Label","default":""},"quantity":{"type":"number","title":"Quantity"},"quantity_label":{"type":"string","title":"Quantity Label","default":""}},"type":"object","required":["description","rate","quantity"],"title":"InvoiceLineItemRequest"},"InvoiceRequest":{"properties":{"invoice_number":{"type":"string","title":"Invoice Number","default":""},"invoice_date":{"type":"string","title":"Invoice Date"},"bill_from_name":{"type":"string","title":"Bill From Name"},"bill_from_address":{"type":"string","title":"Bill From Address","default":""},"bill_from_email":{"type":"string","title":"Bill From Email","default":""},"bill_from_pan":{"type":"string","title":"Bill From Pan","default":""},"bill_to_name":{"type":"string","title":"Bill To Name"},"bill_to_address":{"type":"string","title":"Bill To Address","default":""},"bill_to_gstin":{"type":"string","title":"Bill To Gstin","default":""},"bill_to_email":{"type":"string","title":"Bill To Email","default":""},"exchange_rate":{"type":"number","title":"Exchange Rate","default":90.0},"signature_name":{"type":"string","title":"Signature Name","default":""},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItemRequest"},"type":"array","title":"Line Items"},"idempotency_key":{"type":"string","title":"Idempotency Key","default":""}},"type":"object","required":["invoice_date","bill_from_name","bill_to_name","line_items"],"title":"InvoiceRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Certificates","description":"Create, view, download, and verify tamper-proof certificates"},{"name":"Invoices","description":"Generate tax invoices as downloadable PDFs"},{"name":"Verification","description":"Verify certificate authenticity (single and batch)"},{"name":"Courses","description":"List available courses"},{"name":"Admin","description":"Admin endpoints for certificate and course management (requires X-Admin-Key)"},{"name":"System","description":"Health checks and API metadata"}]}