Client Libraries

Podio Ruby client

This is the official Ruby client for accessing the Podio API. Besides handling setup and authentication it also provides idiomatic Ruby methods for accessing most of the APIs operations. This client library is designed to be minimal and easily integrable into your projects.


Podio is packaged as a gem:


gem install podio

Or you can use Bundler:


gem 'podio'


The main way of using the Podio library is via a singleton client, which you set up like this:


Podio.setup(:api_key => 'YOUR_API_KEY', :api_secret => 'YOUR_API_SECRET')

This initializes a Podio::Client object and assigns it to a thread-local, which is used by all methods in this library.


After the configuration you need to authenticate against the API. The client supports two ways of authentication:

Web Server Flow

The default OAuth flow to be used when you authenticate Podio users from your web application.


    Podio.client.authenticate_with_auth_code('AUTHORIZATION_CODE', redirect_uri)

We recommend using Omniauth for authenticating from a rack-based Ruby app. The Rails sample application on Github demonstrates how to implement the OAuth flow in Ruby on Rails using Omniauth.

App authentication

If you need only to interact with a single Podio app from your code and you don't want to bother with a full login flow, we recommend using this approach.


    Podio.client.authenticate_with_app('APP_ID', 'APP_TOKEN')

Username and Password Flow

If you're writing a batch job or are just playing around with the API, this is the easiest to get started. Do not use this for authenticating users other than yourself, the web server flow is meant for that.


    Podio.client.authenticate_with_credentials('USERNAME', 'PASSWORD')

Basic Usage

After you configured the Podio.client singleton you can use all of the wrapper functions to do API requests. The functions are organized into modules corresponding to the official API documentation. The functions follow a common naming pattern that should be familiar to ActiveRecord users. For example:


# Getting an item

# Posting a status message on space with id 23
Podio::Status.create(23, {:value => 'This is the text of the status message'})

If there is a method missing or you want to do something special, you can use the Faraday connection directly. This allows you to do arbitrary HTTP requests to the Podio API with authentication, JSON parsing and error handling already taken care of. The same examples would look like this:


# Getting an item
response = Podio.connection.get('/item/42')

# Posting a status message on space with id 23
response = do |req|
  req.url '/status/space/23/'
  req.body = {:value => 'This is the text of the status message'}

All the wrapped methods either return a single model instance, an array of instances, or a simple Struct in case of pagination:


# Find all items in an app (paginated)
items = Podio::Item.find_all(app_id, :limit => 20)

# get count of returned items in this call

# get the returned items in an array

# get count of all items in this app

Active Podio

The Podio API is based on REST requests passing JSON back and forth, but we have tried to make the use of this client an experience more similar to using ActiveRecord from Ruby on Rails. That means that all find methods returns model instances with attributes cast to the expected type (string, integer, boolean, datetime, etc.). Also, models can be instantiated using an object array from params in Rails, just like with ActiveRecord Models.

While the models can be used directly from this gem, we encourage everyone using Podio in a Rails project to add models that extends the standard models:


class Item < Podio::Item # Inherits from the base model in the Podio gem

  # Your custom methods, e.g.:
  def application
    @app_instance ||= Application.find(self.app_id)

Error Handling

All unsuccessful responses returned by the API (everything that has a 4xx or 5xx HTTP status code) will throw an exception. All exceptions inherit from Podio::PodioError and have three additional properties which give you more information about the error:


  Podio::Space.create({:name => 'New Space', :org_id => 42})
rescue Podio::BadRequestError => exc
  puts exc.response_body      # parsed JSON response from the API
  puts exc.response_status    # status code of the response
  puts exc.url                # uri of the API request

  # you normally want this one, a human readable error description
  puts exc.response_body['error_description']

On instance methods, however, exceptions are handled in a way more similar to ActiveRecord. These methods returns a boolean indicating if the API request succeeded or not, and makes the code, description and parameters available when the request fails:


@space_contact ={:name => 'Fritz Smith', :birthdate => 70.years.ago})
if @space_contact.create
  # Success
  # Error, check:
  # @space_contact.error_code
  # @space_contact.error_message
  # @space_contact.error_parameters

Full Example


require 'rubygems'
require 'podio'

Podio.setup(:api_key => 'YOUR_API_KEY', :api_secret => 'YOUR_API_SECRET')
Podio.client.authenticate_with_credentials('YOUR_PODIO_ACCOUNT', 'YOUR_PODIO_PASSWORD')

# Print a list of organizations I'm a member of
my_orgs = Podio::Organization.find_all

my_orgs.each do |org|
  puts org.url

Example app on Github

The Rails sample application on Github demonstrates how to authenticate and read/write items to Podio.


git clone git://

This project uses Semantic Versioning.