{"openapi":"3.1.0","info":{"title":"Notapex Public & AI Agent API","version":"1.0.0","summary":"Programmatic REST API for Notapex Study Notes Marketplace, AI Note Converter, and AI Presentation Maker.","description":"Official REST API for Notapex (https://notapex.com). Enables AI agents and developer integrations to search verified academic & competitive exam study notes, inspect transcripts, check pricing plans, and submit handwritten notes for asynchronous AI OCR and structured PDF/PPTX conversion.\n\n### Versioning & Deprecation Policy\nNotapex uses URL-path major versioning (`/api/v1`). Breaking changes are introduced only in new major versions (`/api/v2`). Deprecated endpoints or fields remain operational for a minimum of **12 months (365 days)** after announcement and emit standard RFC 8594 `Sunset` and `Deprecation: true` HTTP headers alongside a `Link: <...>; rel=\"successor-version\"` header.\n\n### Authentication & Scoped Permissions\nPublic catalog discovery (`GET /api/v1/notes`, `GET /api/v1/categories`, `GET /api/v1/pricing`) is accessible without authentication or with `notes:read`. Write and AI conversion operations require OAuth 2.0 Bearer tokens (`/.well-known/oauth-authorization-server`) with PKCE (`S256`) and granular least-privilege scopes (`notes:read`, `notes:write`, `notes:convert`, `channels:read`, `account:read`, `webhooks:manage`), or Sandbox mode (`X-Sandbox-Mode: true`).","termsOfService":"https://notapex.com/terms","contact":{"name":"Notapex Developer & Agent Support","url":"https://notapex.com/docs","email":"support@notapex.com"},"license":{"name":"Proprietary / Public API Terms","url":"https://notapex.com/terms"},"x-api-version":"2026-09-01","x-deprecation-policy":{"minimumNoticeDays":365,"sunsetHeader":true,"deprecationHeader":true,"policyUrl":"https://notapex.com/docs#versioning"}},"externalDocs":{"description":"Notapex API & MCP Developer Documentation","url":"https://notapex.com/docs"},"servers":[{"url":"https://notapex.com","description":"Production API Server"},{"url":"https://notapex.com/api/sandbox","description":"Sandbox / Test Environment (safe non-production mode for AI agent testing)"}],"tags":[{"name":"Discovery","description":"API health, capabilities, and service metadata."},{"name":"Notes","description":"Search, retrieve, and batch-lookup published study notes."},{"name":"Categories","description":"Academic subjects and competitive exam categories."},{"name":"Conversions","description":"Asynchronous AI handwritten-to-PDF and document-to-PPTX conversion jobs."},{"name":"Pricing","description":"Machine-readable subscription plans and AI credit packages."}],"security":[{},{"OAuth2":["notes:read"]},{"BearerAuth":[]},{"ApiKeyAuth":[]}],"paths":{"/api/v1":{"get":{"operationId":"get_api_status","tags":["Discovery"],"summary":"Get API v1 status and capability links","description":"Returns the current health status of the Notapex Public API v1, supported authentication flows, rate-limit policy, MCP server endpoint, and links to OpenAPI and OAuth 2.0 metadata.","security":[{}],"responses":{"200":{"description":"API status and discovery pointers returned successfully.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStatusResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/notes":{"get":{"operationId":"list_notes","tags":["Notes"],"summary":"Search and list published study notes with cursor pagination","description":"Returns a cursor-paginated list of verified study notes across academic and competitive exam categories. Supports full-text search via `q` and filtering by `category`.","security":[{},{"OAuth2":["notes:read"]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Search query matching note title, subject, or summary (e.g., \"graph theory\", \"organic chemistry\", \"polity\").","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"description":"Filter by category slug (e.g., \"computer-science\", \"jee-neet\", \"upsc\", \"ssc-railways\", \"mathematics\").","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of notes to return per page (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Opaque pagination cursor returned in `pagination.next_cursor` from the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of study notes.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/notes/{slug}":{"get":{"operationId":"get_note_by_slug","tags":["Notes"],"summary":"Get detailed metadata and preview transcript for a study note","description":"Retrieves a single study note by its unique slug or identifier, including subject metadata, page count, pricing in INR, author details, and structured summary.","security":[{},{"OAuth2":["notes:read"]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Unique URL slug or ID of the study note (e.g., \"unit-4-graph-theory-terminology-and-paths\").","schema":{"type":"string"}}],"responses":{"200":{"description":"Detailed study note object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteDetailResponse"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/categories":{"get":{"operationId":"list_categories","tags":["Categories"],"summary":"List all study note categories and exam tracks","description":"Returns all supported academic subjects and competitive exam tracks on Notapex (JEE, NEET, UPSC, SSC, Railways, Computer Science, Mathematics).","security":[{},{"OAuth2":["channels:read","notes:read"]}],"responses":{"200":{"description":"List of categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryListResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/conversions":{"post":{"operationId":"create_conversion_job","tags":["Conversions"],"summary":"Submit an asynchronous AI note conversion job (202 Accepted)","description":"Enqueues an asynchronous AI job to convert handwritten note images/PDFs into a clean, structured study PDF (or typed documents into editable PowerPoint `.pptx` slides). Supports safe retries via the `Idempotency-Key` header and returns `202 Accepted` with a pollable job status URL (`/api/v1/jobs/{jobId}`).","security":[{"OAuth2":["notes:convert"]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"name":"X-Sandbox-Mode","in":"header","required":false,"description":"Set to \"true\" to run in non-destructive sandbox mode without consuming credits.","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionJobRequest"}}}},"responses":{"202":{"description":"Conversion job accepted and queued for asynchronous processing.","headers":{"Location":{"description":"URL to poll for the asynchronous job status.","schema":{"type":"string","format":"uri"}},"Retry-After":{"description":"Recommended interval in seconds before polling the job status URL.","schema":{"type":"integer","default":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobAcceptedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/jobs/{jobId}":{"get":{"operationId":"get_conversion_job_status","tags":["Conversions"],"summary":"Poll status of an asynchronous conversion job","description":"Retrieves the real-time status (`queued`, `processing`, `completed`, `failed`), progress percentage, and output download URL for an asynchronous AI conversion job.","security":[{},{"OAuth2":["notes:convert","notes:read"]}],"parameters":[{"name":"jobId","in":"path","required":true,"description":"Unique identifier of the conversion job returned by `POST /api/v1/conversions`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Current status and output artifacts of the conversion job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/batch":{"post":{"operationId":"batch_lookup_notes","tags":["Notes"],"summary":"Batch lookup multiple study notes in a single request","description":"Allows AI agents to retrieve up to 50 study notes by slug or ID in a single bulk HTTP call, avoiding sequential round-trips. Supports `Idempotency-Key` for safe retries.","security":[{},{"OAuth2":["notes:read"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchLookupRequest"}}}},"responses":{"200":{"description":"Batch results for the requested study notes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchLookupResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/pricing":{"get":{"operationId":"get_pricing_plans","tags":["Pricing"],"summary":"Get machine-readable pricing tiers and AI credit plans","description":"Returns Notapex subscription tiers, prepaid AI credit packs, validity periods, and included features in structured JSON.","security":[{}],"responses":{"200":{"description":"Structured pricing plans and free tier specifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingPlansResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 Authentication supporting Authorization Code with PKCE (S256) and Client Credentials flows. Discovery metadata at https://notapex.com/.well-known/oauth-authorization-server","x-pkce-required":true,"x-code-challenge-methods":["S256"],"x-authorization-server-metadata":"https://notapex.com/.well-known/oauth-authorization-server","x-protected-resource-metadata":"https://notapex.com/.well-known/oauth-protected-resource","flows":{"authorizationCode":{"authorizationUrl":"https://notapex.com/api/oauth/authorize","tokenUrl":"https://notapex.com/api/oauth/token","refreshUrl":"https://notapex.com/api/oauth/token","scopes":{"notes:read":"Read published study notes, metadata, summaries, transcripts, and academic categories.","notes:write":"Create, update, and upload study notes, attachments, and study bundles.","notes:convert":"Submit handwritten notes or documents for AI OCR transcription, PDF formatting, and PPTX generation.","channels:read":"Browse creator channels, verified educators, and curated exam collections.","account:read":"Read authenticated user profile, subscription plan, and AI credit balance.","webhooks:manage":"Register and manage webhook endpoints for asynchronous conversion job notifications."}},"clientCredentials":{"tokenUrl":"https://notapex.com/api/oauth/token","scopes":{"notes:read":"Read published study notes, metadata, summaries, transcripts, and academic categories.","notes:write":"Create, update, and upload study notes, attachments, and study bundles.","notes:convert":"Submit handwritten notes or documents for AI OCR transcription, PDF formatting, and PPTX generation.","channels:read":"Browse creator channels, verified educators, and curated exam collections.","account:read":"Read authenticated user profile, subscription plan, and AI credit balance.","webhooks:manage":"Register and manage webhook endpoints for asynchronous conversion job notifications."}}}},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer access token issued by https://notapex.com/api/oauth/token"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Self-serve developer/agent API key generated via /dashboard or /api/oauth/register"}},"parameters":{"IdempotencyKeyHeader":{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique client-generated UUID (RFC 4122) to guarantee idempotent execution across network retries for up to 24 hours.","schema":{"type":"string","minLength":8,"maxLength":128,"example":"idem_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"}}},"headers":{"RateLimitLimit":{"description":"Maximum number of requests permitted in the current time window.","schema":{"type":"integer","example":120}},"RateLimitRemaining":{"description":"Remaining number of requests permitted in the current window.","schema":{"type":"integer","example":119}},"RateLimitReset":{"description":"Seconds remaining until the rate-limit window resets.","schema":{"type":"integer","example":60}}},"responses":{"BadRequestError":{"description":"Invalid request parameters or malformed payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnauthorizedError":{"description":"Missing, expired, or insufficient OAuth 2.0 Bearer token. Inspect the WWW-Authenticate response header for protected resource metadata.","headers":{"WWW-Authenticate":{"description":"RFC 9728 / OAuth 2.0 challenge pointing to /.well-known/oauth-protected-resource","schema":{"type":"string","example":"Bearer resource_metadata=\"https://notapex.com/.well-known/oauth-protected-resource\", scope=\"notes:convert\""}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"Requested study note or job resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitedError":{"description":"Rate limit exceeded. Wait for the duration specified in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Unexpected internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["error","code","message","status","request_id"],"properties":{"error":{"type":"boolean","enum":[true]},"code":{"type":"string","enum":["INVALID_REQUEST","UNAUTHORIZED","INSUFFICIENT_SCOPE","NOT_FOUND","CONFLICT","RATE_LIMITED","INTERNAL_ERROR"],"description":"Machine-readable error code for deterministic handling."},"message":{"type":"string","description":"Human- and agent-readable explanation of the error."},"status":{"type":"integer","description":"HTTP status code."},"request_id":{"type":"string","description":"Unique trace identifier for debugging."},"resolution_hint":{"type":"string","description":"Actionable recommendation for the calling agent to recover from the error."},"docs_url":{"type":"string","format":"uri","example":"https://notapex.com/docs#errors"}}},"NoteItem":{"type":"object","required":["id","slug","title","category","subject","pages","price_inr","is_free","summary","url"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"subject":{"type":"string"},"author":{"type":"string"},"language":{"type":"string","default":"en"},"pages":{"type":"integer"},"price_inr":{"type":"number"},"is_free":{"type":"boolean"},"rating":{"type":"number"},"summary":{"type":"string"},"url":{"type":"string","format":"uri"},"updated_at":{"type":"string","format":"date-time"}}},"CursorPagination":{"type":"object","required":["limit","has_more","next_cursor"],"properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"total_estimate":{"type":"integer"}}},"NoteListResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NoteItem"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}}},"NoteDetailResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/NoteItem"}}},"CategoryItem":{"type":"object","required":["id","slug","name","description","exam_types","note_count"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"exam_types":{"type":"array","items":{"type":"string"}},"note_count":{"type":"integer"}}},"CategoryListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CategoryItem"}}}},"ConversionJobRequest":{"type":"object","required":["source_url","mode"],"properties":{"source_url":{"type":"string","format":"uri","description":"HTTPS URL of the handwritten PDF, JPG, PNG, or DOCX file to convert."},"mode":{"type":"string","enum":["faithful_exact_copy","structured_study_notes","ppt_presentation"],"description":"Conversion mode: faithful_exact_copy (verbatim words + clean formatting), structured_study_notes, or ppt_presentation."},"title":{"type":"string","description":"Optional document title."},"sandbox":{"type":"boolean","default":false,"description":"Run in sandbox test mode without consuming production credits."}}},"AsyncJobAcceptedResponse":{"type":"object","required":["job_id","status","status_url","poll_interval_seconds","created_at"],"properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing"]},"status_url":{"type":"string","format":"uri"},"poll_interval_seconds":{"type":"integer"},"idempotency_key":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"JobStatusResponse":{"type":"object","required":["job_id","status","progress","created_at"],"properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"progress":{"type":"integer","minimum":0,"maximum":100},"output_url":{"type":["string","null"],"format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"BatchLookupRequest":{"type":"object","required":["slugs"],"properties":{"slugs":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"Array of study note slugs or IDs to fetch in a single request."}}},"BatchLookupResponse":{"type":"object","required":["data","found_count","missing_slugs"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NoteItem"}},"found_count":{"type":"integer"},"missing_slugs":{"type":"array","items":{"type":"string"}}}},"PricingPlansResponse":{"type":"object","required":["currency","credit_system","plans"],"properties":{"currency":{"type":"string"},"credit_system":{"type":"object"},"plans":{"type":"array","items":{"type":"object","required":["id","name","price_inr","credits","validity_days","features"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"price_inr":{"type":"number"},"credits":{"type":"integer"},"validity_days":{"type":"integer"},"features":{"type":"array","items":{"type":"string"}}}}}}},"ApiStatusResponse":{"type":"object","required":["service","version","status","openapi_url","mcp_url","oauth_metadata_url","scopes_supported"],"properties":{"service":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"openapi_url":{"type":"string","format":"uri"},"openapi_yaml_url":{"type":"string","format":"uri"},"mcp_url":{"type":"string","format":"uri"},"docs_url":{"type":"string","format":"uri"},"sandbox_url":{"type":"string","format":"uri"},"oauth_metadata_url":{"type":"string","format":"uri"},"protected_resource_metadata_url":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"type":"string"}}}}}}}