API Reference

The Jiroshi REST API provides programmatic access to all core platform resources, including instructors, students, courses, enrollments, and related operational data. It is intended for building custom integrations, instructor-facing tools, internal services, and automated workflows on top of the Jiroshi platform.

The API follows standard REST conventions, uses JSON for all request and response payloads, and is versioned to ensure backward compatibility as the platform evolves. Authentication, authorization, and rate limiting are enforced consistently across all endpoints.

This documentation describes the available endpoints, request/response formats, authentication mechanisms, error handling conventions, and operational constraints. All the API endpoints are subject to change as this is a MVP Version of the API and new platform capabilities will be introduced.

https://api.jiroshi.com/api/v1/public

Jiroshi uses API keys to authenticate and authorize access to its REST API. API keys are scoped to your account and must be included with every request to protected endpoints.

You can create and manage API keys from the Jiroshi Dashboard. Each key pair consists of a Public Key (pk) and a Secret Key (sk), each intended for different security contexts.

To generate a new API key, navigate to the Manage API Keys section from the dashboard sidebar. On the Manage API Keys page:

• Enter a meaningful name for the API key to identify its purpose.
• Select an expiration period. Available options include 1 week, 1 month, 1 year, or never.
• Generate the API key.

Jiroshi distinguishes between public and secret API keys to enforce proper security boundaries:

• Public Key (pk) - Safe to use in client-side applications such as web or mobile frontends. Required for all public-facing API calls.
  Sample Public Key (pk)

  bash

  Copy

  pk:12a3b456-1ab2-3c45-4d67-21f72ad886f3:RK07B89pGD4J3-VypELpwDX4z1ZX0yF1R_0au6EZibU=

• Secret Key (sk) - Must never be exposed on the frontend. Intended strictly for secure server-to-server operations, such as payment processing or privileged administrative actions.
  Sample Secret Key (sk)

  bash

  Copy

  sk:12a3b456-1ab2-3c45-4d67-21f72ad886f3:RK07B89pGD4J3-VypELpwDX4z1ZX0yF1R_0au6EZibU=

At present, all documented API endpoints require only the use of the Public Key (pk). While Secret Keys are not actively used in the current API surface, they are reserved for upcoming features and enhanced security-sensitive workflows.

Each API endpoint in this documentation is explicitly tagged to indicate whether it requires a pk or sk, allowing you to clearly distinguish frontend-safe and server-only operations.

API keys are revokable. When a key is revoked, it is no longer valid and cannot be used to access the API. This ensures that compromised keys are quickly rendered ineffective.

API keys can be revoked from the Jiroshi Dashboard by simply deleting a particular key. It also gets revoked on expiration.

All authenticated requests to the Jiroshi API must include a valid API key in the request headers. The API uses this key to identify the requesting account and to enforce access control rules.

API keys are passed using the x-api-keyheader. Requests missing this header or providing an invalid key will be rejected.

x-api-key: <YOUR_API_KEY>

The Jiroshi API performs strict validation on every API key provided with a request. A request will fail if any of the following conditions apply:

• The API key is missing from the request headers.
• The API key is malformed, invalid, or does not exist.
• The API key has expired.
• The API key type does not match the endpoint requirements (for example, using a Secret Key where a Public Key is expected, or vice versa).

All errors related to API key authentication and validation use the standardized error codeAPI_KEY_ERR.

The HTTP status code and error message will vary depending on the failure scenario (for example, missing credentials, expired keys, or invalid key usage). Detailed information about response formats, error structures, and status codes is covered in a later section of this documentation.

{
  "status": false,
  "results": false,
  "message": "API key missing",
  "data": null,
  "error_code": "INVALID_TOKEN_ERR"
}

All Jiroshi API responses follow a consistent, envelope-based JSON structure. This applies to both successful and failed requests, allowing clients to reliably parse and handle responses across all endpoints.

{
  "status": true,
  "results": true,
  "message": "Success",
  "data": {
    "id": "c1a2b3d4-e89b-12d3-a456-426614174000",
    "name": "Introduction to Backend Development",
    "is_active": true,
    "created_at": "2025-01-12T10:42:31Z"
  },
  "error_code": null
}

• status - Indicates whether the request was successfully processed (true) or failed (false).
• results - Indicates whether thedata field is non-null.
• message - A human-readable success or error message.
• data - The response payload containing resource data.
• error_code - A machine-readable error identifier, ornull for successful responses.

Endpoints that return collections use a paginated response format. Pagination metadata is included alongside the result set.

{
  "status": true,
  "results": true,
  "message": "Successfully Fetched",
  "data": {
    "results": [
      {
        "uuid": "a12f3c9b-4e91-44de-bf6a-9f1a2a6d90ab",
        "title": "Advanced Django Course",
        "description": "",
        "thumbnail": "<thumbnail_url>",
        "duration": "39600.9667",
        "created_at": "2025-10-02T14:20:11.544767Z",
        "is_enrolled": false
      },
      {
        "uuid": "a12f3c9b-4e91-44de-bf6a-9f1a2a6d90ab",
        "title": "Learn Python",
        "description": "",
        "thumbnail": "<thumbnail_url>",
        "duration": "15876.9667",
        "created_at": "2025-10-02T14:20:11.544767Z",
        "is_enrolled": false
      },
      {
        "uuid": "a12f3c9b-4e91-44de-bf6a-9f1a2a6d90ab",
        "title": "Learn JavaScript",
        "description": "",
        "thumbnail": "<thumbnail_url>",
        "duration": "15876.9667",
        "created_at": "2025-10-02T14:20:11.544767Z",
        "is_enrolled": false
      }
    ],
    "pagination": {
      "count": 3,
      "total_pages": 1,
      "current_page": 1,
      "next": null,
      "previous": null
    }
  },
  "error_code": null
}

• results - A list of resource objects for the current page.
• pagination - Metadata used to navigate large result sets.

Error responses use the same envelope structure, withstatus andresults set tofalse,data set tonullor maybe some structured error, and a non-nullerror_code.

{
  "status": false,
  "results": false,
  "message": "API key missing",
  "data": null,
  "error_code": "INVALID_TOKEN_ERR"
}

Jiroshi APIs use standardized error codes to help clients reliably identify and handle different failure scenarios. Error codes are string literals that remain consistent across API versions and environments, even if the human-readable error message changes.

Whenever an error occurs, the response includes a non-nullerror_code field along with an appropriate HTTP status code and message.

• INTEGRITY_ERR - Database integrity constraint violations, such as foreign key or uniqueness mismatches.
  INTEGRITY_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "Database integrity error !",
    "data": null,
    "error_code": "INTEGRITY_ERR"
  }

• VALIDATION_ERR - Invalid input data or failed validation rules based on the request payload.
  VALIDATION_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "API key missing",
    "data": null,
    "error_code": "VALIDATION_ERR"
  }

• API_KEY_ERR - Issues related to API key authentication, including missing, invalid, malformed, or expired API keys.
  API_KEY_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "API key missing",
    "data": null,
    "error_code": "API_KEY_ERR"
  }

• INVALID_TOKEN_ERR - Student authentication failures due to missing, invalid, malformed, or expired access or refresh tokens.
  INVALID_TOKEN_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "Student not authenticated",
    "data": null,
    "error_code": "INVALID_TOKEN_ERR"
  }

• ACCESS_DENIED_ERR - Unauthorized access attempts to resources that do not belong to the requesting tenant.
  ACCESS_DENIED_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "Access denied to this resource !",
    "data": null,
    "error_code": "ACCESS_DENIED_ERR"
  }

• ALREADY_EXISTS_ERR - Attempt to create a resource that already exists.
  ALREADY_EXISTS_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "Record already exists !",
    "data": null,
    "error_code": "ALREADY_EXISTS_ERR"
  }

• NOT_FOUND_ERR - Requested resource could not be found.
  NOT_FOUND_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "Record not found !",
    "data": null,
    "error_code": "NOT_FOUND_ERR"
  }

• INTERNAL_ERR - An unhandled server-side exception. If this error is encountered, please report it with request details as soon as possible.
  INTERNAL_ERR

  json

  Copy

  {
    "status": false,
    "results": false,
    "message": "Internal Server Error",
    "data": null,
    "error_code": "INTERNAL_ERR"
  }

Clients are strongly encouraged to rely onerror_code values and HTTP Response codes for programmatic error handling rather than parsing response messages, which are intended primarily for human readability.

Pagination is applied to all listing APIs in Jiroshi. By default, the API uses cursor-based pagination to ensure faster response times and better performance on large datasets.

GET /courses/?pagination=page

When using cursor-based pagination, the response includes navigation URLs and encoded cursor values that can be used to fetch the next or previous set of results.

{
  "status": true,
  "results": true,
  "message": "Successfully Fetched",
  "data": {
    "results": [
      {
        "uuid": "723a743c-a012-40ee-bebc-dc24c48818bf",
        "title": "Course Dummy v3",
        "description": "Test Desc",
        "thumbnail": "https://jiroshi-static-dev.s3.ap-south-1.amazonaws.com/course-thumbnail/...",
        "duration": "15.9667",
        "created_at": "2025-11-01T06:41:03.008653Z",
        "is_enrolled": false
      },
      {
        "uuid": "a9fb5567-a9ae-4980-add7-763c2aca0351",
        "title": "Course Test V2",
        "description": "",
        "thumbnail": "<course_thumbnail>",
        "duration": "148.3854",
        "created_at": "2025-10-19T19:40:28.598591Z",
        "is_enrolled": false
      }
    ],
    "pagination": {
      "next": "https://api.jiroshi.com/api/v1/public/courses/?cursor=...",
      "previous": "https://api.jiroshi.com/api/v1/public/courses/?cursor=...",
      "next_cursor": "cD0yMDI1LTEwLTE5KzE5JTNBNDAlM0EyOC41OTg1OTElMkIwMCUzQTAw",
      "previous_cursor": "cj0xJnA9MjAyNS0xMC0xOSsxOSUzQTQwJTNBMjguNTk4NTkxJTJCMDAlM0EwMA=="
    }
  },
  "error_code": null
}

• next - Fully constructed URL to fetch the next page of results, if available.
• previous - Fully constructed URL to fetch the previous page of results, if available.
• next_cursor - Encoded cursor value for fetching the next set of results programmatically.
• previous_cursor - Encoded cursor value for fetching the previous set of results.

Clients may either follow the provided pagination URLs directly or extract and reuse cursor values as query parameters in subsequent requests.

GET /courses/?cursor=<NEXT_CURSOR_VALUE>

GET /courses/?cursor=<PREVIOUS_CURSOR_VALUE>

GET /courses/?pagination=page&page=1&page_size=10

{
  "status": true,
  "results": true,
  "message": "Successfully Fetched",
  "data": {
    "results": [
      {
        "uuid": "723a743c-a012-40ee-bebc-dc24c48818bf",
        "title": "Course Dummy",
        "description": "Description",
        "thumbnail": "<thumbnail_url>",
        "duration": "1599.9667",
        "created_at": "2025-11-01T06:41:03.008653Z",
        "is_enrolled": false
      }
    ],
    "pagination": {
      "count": 21,
      "total_pages": 3,
      "current_page": 3,
      "next": null,
      "previous": "https://api.jiroshi.com/api/v1/public/courses/?page=2&page_size=10&pagination=page"
    }
  },
  "error_code": null
}

Jiroshi APIs provide selection and filtering mechanisms to optimize data retrieval, reduce response payload size, and improve performance for data-intensive endpoints.

Selections allow clients to explicitly specify which fields should be returned in the response. This is particularly useful for list and retrieve APIs where returning the full object is unnecessary.

For example, when displaying a list of lessons where only the title and description are required, selections can be used to fetch only those fields.

GET /courses/<course_id>/lessons/?selections=title,description

• Only fields included in selectionsare returned in the response.
• Selections are restricted to a predefined set of allowed fields per API.
• Invalid or unsupported selection fields are silently ignored.
• If no selections are provided, or all provided selections are invalid, the API returns all allowed fields by default.

Not all APIs support selections. Wherever supported, the list of allowed selectable fields is documented explicitly for that endpoint.

Listing APIs support a set of generic filters that allow clients to narrow down results based on search terms, ordering, and date ranges.

To perform a generic search across all searchable fields, use thesearch query parameter.

GET /courses/?search=backend

Field-specific searches can also be performed by using the field name directly as a query parameter.

GET /courses/?title=django

Searchable fields vary by API and are documented individually for each endpoint.

All listing APIs apply a default ordering of-created_at(descending by creation time).

This behavior can be overridden using theordering query parameter.

# Ascending order by duration
GET /courses/?ordering=duration

# Descending order by duration
GET /courses/?ordering=-duration

Date range filtering follows a consistent naming convention for all supported date fields.

• <field>_after - Filters records after the specified date.
• <field>_before - Filters records before the specified date.

GET /courses/?created_at_after=2025-01-01T00:00:00Z&created_at_before=2025-01-31T23:59:59Z

Jiroshi currently only supports standard JWT-based authentication mechanism for student authentication and session management. This flow is used for all student-facing actions such as sign-up, login, enrollment, and course access.

Upon successful authentication, a student is issued an access token and a refresh token. The access token is used to authenticate API requests, while the refresh token is used to obtain new access tokens when the current one expires.

All authentication APIs are accessed using the Public API Key (pk) of an instructor. When a student authenticates using an instructor’s public key, that student is permanently associated with the corresponding instructor tenant.

This tenant-based authentication model ensures strict isolation between instructors. Tokens issued under one instructor’s API key cannot be used to access resources belonging to another instructor.

Jiroshi adapts its authentication token handling based on the detected client environment to ensure maximum security while supporting multiple application types.

When a request is identified as originating from a browser environment, refresh tokens are issued and stored exclusively via HTTP-only cookies. These cookies are inaccessible to browser-side JavaScript and are automatically included in subsequent refresh requests by the browser.

In this mode, refresh tokens are never exposed in API responses or request payloads, significantly reducing the risk of token theft via XSS or client-side compromise.

For non-browser clients such as mobile applications, desktop clients, or backend services, refresh tokens are returned directly in the API response payload. Subsequent refresh requests must include the refresh token explicitly in the request body.

This mode is intended only for environments where secure storage of tokens is handled by the client platform itself.

During local development, strict cookie policies (SameSite, Secure) can sometimes hinder testing on localhost. You can switch to a developer-friendly mode by setting the following header:

X-Client-Type: dev

Effect: In this mode, just like with non-browser clients, the refresh token is transported via the request and response payloads instead of cookies. This makes it easier to inspect and manage tokens manually during development.

In certain edge cases-such as React Native or Electron-based applications-the client may be incorrectly detected as a browser. In such scenarios, token handling can be explicitly forced to API mode by setting the following request header:

X-Client-Type: non-browser

Jiroshi reserves the right to introduce additional validation, restrictions, or rate limits on forced API mode usage to prevent abuse.