License Gem Version Yard Docs

Build Status Coverage Status Code Climate Issue Count Inline docs


Official Ruby Client for the PortaText API.


  • The endpoint tests should also serve as good doucmentation on how to use the API.
  • General PortaText documentation (including the REST API) can be found at the PortaText wiki.


Add this library to your Gemfile.

gem 'portatext'

Basic use

Getting a client instance

The first thing is to get a Client instance, for example the Net::HTTP implementation:

require 'portatext'
client =

(Optional) Set your logger

You can optionally set a Logger compatible logger:

client.logger = my_logger

By default, the client will use a logger pointing to /dev/null


You can authenticate to the endpoints by using your API key or your username/password. This translates to either doing this:

client.api_key = api_key

Or this:

client.credentials = [username, password]

When you specify a username and password instead of an api key, the sdk will automatically login and get a session token when needed.

Using the endpoints

All the API commands can be found in the command/api directory. The client offers a way to instantiate them by just calling them by their name.

Quick example

As an example, to create a template, you would do:

result = client
  .templates                       # Get an instance of the Templates endpoint.
  .text('The text of my template')
  .description('My first template')
  .post                            # Call the Templates endpoint with a POST.

To get a template by id:

result =

Or, to get all the templates:

result = client.templates.get

The result

After calling an endpoint, one of two things can happen:

Also, when possible, your PortaText exception will contain a Result object that can be retrieved by using the result accessor on the exception. This is usually useful for the ClientError exception, where you will be able to see if a field was missing or different than what was expected.

Testing for success

if result.success?

Getting error strings back from the server

if !result.errors.nil?
  result.errors.each do |e|
    puts e

Getting data back from the server

if result.success
  data =


This project uses rake. Current tasks include:

  • test: Runs MiniTests.
  • rubocop: Runs RuboCop.
  • default: This is the default task, and will run all the other tasks.

Running a rake task

To run a task, just do:

rake test


To contribute:

  • Make sure you open a concise and short pull request.
  • Throw in any needed unit tests to accomodate the new code or the changes involved.
  • Run rake and make sure everything is ok before submitting the pull request (make rubocop happy).
  • Your code must comply with the GitHub ruby style.
  • If your code is accepted, it will belong to PortaText and will be published under the Apache2 License.


The source code is released under Apache 2 License.

Check LICENSE file for more information.