Unlocking Leantime’s Power: A Guide to the JSON-RPC API

As developers and technical users, we’re always looking for ways to extend our tools and integrate them into our workflows. At Leantime, we’ve designed our API with flexibility and power in mind, using JSON-RPC instead of the more common REST approach. In this tech corner post, I’ll walk you through what makes our API special and how to start using it in your projects.

What is JSON-RPC (and Why It’s Better Than You Think)

Unlike REST APIs that focus on resources and CRUD operations, JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol that uses JSON for data encoding. While REST is widely adopted, JSON-RPC offers some distinct advantages that make it perfect for Leantime’s architecture:

1. Transaction-focused: Instead of thinking about resources, you’re calling methods directly. This means more flexibility in what you can do.
2. Single endpoint: All requests go to the same URL, with the specific operation defined in the request body.
3. Direct service layer access: This is where the magic happens – our JSON-RPC API gives you access directly to Leantime’s service methods, providing much deeper integration possibilities.

If you’ve never worked with JSON-RPC before, think of it as making function calls to a remote system. Instead of asking for a “task” resource with a GET request, you’re calling getTicket() and passing parameters. This approach aligns perfectly with how Leantime is built internally.

Getting Started with Authentication

Before making any API calls, you’ll need to create an API key:

1. Navigate to “Company Settings” in your Leantime instance
2. Create a new API Key
3. Assign appropriate roles and project access to control what this key can do
4. Save the secret key somewhere secure – you’ll only see it once!

Once you have your key, you’ll include it in the x-api-key header for all requests:

curl https://your-leantime-domain.com/api/jsonrpc
   -H "x-api-key: YOUR_API_KEY"
   -H "Content-Type: application/json"

Making Your First API Call

All API requests are sent to a single endpoint: /api/jsonrpc

Let’s say you want to fetch a specific task (or “ticket” as it’s called in our codebase). Here’s how you’d structure your request:

{
  "method": "leantime.rpc.tickets.getTicket",
  "jsonrpc": "2.0",
  "id": "1",
  "params": {"id": "9"}
}

Let’s break down the components:

• method: Follows the format leantime.rpc.[domain].[method]. In this case, we’re calling the getTicket method in the tickets domain.
• jsonrpc: The version of the protocol (always “2.0”).
• id: A unique identifier for this request/response pair.
• params: The parameters to pass to the method, as a JSON object.

The server will respond with a JSON object containing either a result or an error:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "9",
    "title": "Implement API documentation",
    "description": "Create comprehensive docs for the JSON-RPC API",
    // ... other ticket properties
  }
}

GET Requests (When You Need Them)

While POST requests are recommended, you can also use GET requests when necessary. The format is similar, but the params property needs to be base64 encoded and then URL encoded:

https://your-leantime-domain.com/api/jsonrpc/?method=leantime.rpc.tickets.getTicket&jsonrpc=2.0&id=1&params=eyJpZCI6IjkifQ%3D%3D

The params value eyJpZCI6IjkifQ%3D%3D is the base64 (and URL-encoded) version of {"id":"9"}.

Going Beyond: What Can You Do?

One of the powerful aspects of our JSON-RPC approach is that you have access to all service methods in Leantime. This means you can do things like:

• Create new tasks or projects
• Update project statuses
• Retrieve project analytics
• Manage users and permissions
• Create and manage milestones

The method naming convention makes it intuitive to discover functionality:

• leantime.rpc.projects.getAllProjects
• leantime.rpc.tickets.addTicket
• leantime.rpc.goalcanvas.getAllGoals

Real-World Use Cases

Our JSON-RPC API opens up countless integration possibilities:

1. Automated Reporting: Pull project data for custom dashboards and reports
2. Workflow Automation: Create tickets automatically based on external triggers
3. Status Synchronization: Keep Leantime in sync with other tools in your stack
4. Bulk Operations: Make batch changes across multiple projects or tickets
5. Custom Interfaces: Build specialized UIs for specific team needs

Example: Creating a New Task

Let’s look at a complete example of creating a new task:

curl -X POST https://your-leantime-domain.com/api/jsonrpc \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "leantime.rpc.tickets.addTicket",
    "jsonrpc": "2.0",
    "id": "create-task-123",
    "params": {
      "headline": "Research API integration options",
      "type": "task",
      "description": "Investigate different ways to integrate with external APIs",
      "projectId": "42",
      "editorId": "15",
      "priority": "3"
    }
  }'

Wrapping Up

Leantime’s JSON-RPC API provides a powerful way to extend and integrate our platform into your workflows. While it might feel different than traditional REST APIs at first, the transaction-focused approach gives you direct access to Leantime’s internal service methods, enabling deeper and more flexible integrations.

We’re constantly expanding our API capabilities, so check our documentation for the latest available methods and parameters.

Have you built something interesting with our API? We’d love to hear about it in the comments below!

Ready to get started? Create your API key in Leantime today and try out your first API call. Have questions? Drop them in the comments or reach out to our support team.