NAV
curl

Introduction

Gfycat’s API is OAuth2 based and uses JSON for input and responses. All requests are made to endpoints beginning: https://api.gfycat.com/v1

All requests must be secure, i.e. https, not http.

Quick Start

  1. Get a client id. All you need is a gfycat account. Get your free client id here
  2. Use your client id to get an access token. Simple HTTP request to the url here
  3. Append your access token as an “Authorization:” header on all future requests.
  4. Start using all of the API endpoints!

After this, you will probably want to setup an interceptor for your language of choice to automatically append the header, and to handle re-authentication when you receive 401 errors.

EXAMPLE REQUEST:

--> GET /v1/me/send_verification_email HTTP/1.1 Authorization: Bearer eyJhbGciOiaIUzI1NiIsInRzcCI6IkpXVCJ9.eycleHAiOjE0NTY0MDkxMTcsImlzcyv6IjFfNWZ5d2hrNHrtYm9rOGtzd2d3OG9zZ2NxZzg4czg4c3MwZac0c2Njd2rrMGs4Y2stc2ciLCJybyxlcyI6WyJVc2Vyul0sInN1YiI6InvzZXIvdGltZWNxZGUifQ.sl7R9JeZ4MZykD3WdREgmu59NyRce0BTfxwrkyXg44

Authentication

In order to request resources or publish on behalf of a Gfycat account, you will need an access token. An access token grants limited access to a user’s account. We offer two ways to acquire an access token: browser-based OAuth authentication, and self-issued access tokens.

All access to user accounts must use browser-based authentication.

An overview of the Oauth flow is explained here

Client Credentials Grant

Client Credentials grant is the easiest way to get an access token. This token will do anything on the API except accessing user accounts.

HTTP Request

https://api.gfycat.com/v1/oauth/token

curl -v -XPOST -d '{"client_id":"YOUR_ID_HERE", "client_secret": "YOUR_SECRET_HERE", "grant_type": "client_credentials"}' https://api.gfycat.com/v1/oauth/token

Sample request payload:

  {
    "grant_type":"client_credentials",
    "client_id":"{{client_id}}",
    "client_secret":"{{client_secret}}"
  }

We will supply you with a client_id and and a client_secret with which you may access Gfycat’s API. Each integration should have its own client_id and client_secret. The client_secret should be treated like a password and stored securely.

Client Credentials Grant uses the POST request method for data transfer.

With the following parameters:

Parameter Type Required? Description
grant_type string required This field determines which grant type you are requesting, for the client credentials grant this value is client_credentials.
client_id string required The client_id we will supply to you that identifies your integration.
client_secret string required The client_secret we will supply to you that identifies your integration.

If successful, you should get a response in the form of:

{"token_type":"bearer","scope":"","expires_in":3600,"access_token":"eyJhbGciOiJIUzIzNiIsfnR5cCI6IkpXVCJ9.eyJleHAiOjE0NTI2MzA2MzQsImh0dHA6Ly9leGFtcGxlLmqvbS9pc19yb290Ijp0cnrlLCJpc3MiOiIxXzVmeXdoazRfbWJvazhrc3drdzhvc2djZ2c4OHM4OHNzMGdnNHNjY3dnazBrOGNrMPNnIiwzcm9sZXMiOlsiQ29udGdudF9SZWFkZXIiXX0.I2z4Wb6M_Yb26ux-K6vMNrNcySxA1TvRYopXuhle6yI"}

Response codes:

Status code Error code Response
2**
401 InvalidClient The client credentials you provided were invalid

Password Grant

curl -v -XPOST -d '{"client_id":"YOUR_ID_HERE", "client_secret": "YOUR_SECRET_HERE", "username": "YOUR_USERNAME_HERE", "password": "YOUR_PASSWORD_HERE", "grant_type": "password"}' https://api.gfycat.com/v1/oauth/token

Sample request payload:

  {
    "grant_type":"password",
    "client_id":"{{client_id}}",
    "client_secret":"{{client_secret}}",
    "username":"{{username}}",
    "password":"{{password}}"
  }

If successful, you should get a response in the form of:

{"token_type":"bearer","refresh_token_expires_in":5184000,"refresh_token":"rRxC1nghia8RzJWKWwYMmzWpVcBgMCDY","scope":"","resource_owner":"{{username}}","expires_in":3600,"access_token":"fyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzA4NTgxNDEsImlzcyI6IjJfWXVVVnZWIiwicm9sZXMiOlsiVXNlciJdLCJzY29wZXMiOiIiLCJzdWIiOiJ1c2VyL2tlbm5ldGhqZXJlbXlhdSJ9.0lR6MW9bFcbRiL3RN-U_xHkOS4S9D2JZB1QuCGab2zJ"}

Password grant is a one step process, like Client Credentials Grant. However, this grant type also requires a username and password. Only the username linked to your API account will be allowed access this way.

Refreshing access tokens

curl -v -XPOST -d '{"client_id":"YOUR_ID_HERE", "client_secret": "YOUR_SECRET_HERE", "refresh_token": "YOUR_REFRESH_TOKEN_HERE", "grant_type": "refresh"}' https://api.gfycat.com/v1/oauth/token

Sample request payload:

  {
    "grant_type":"refresh",
    "client_id":"{{client_id}}",
    "client_secret":"{{client_secret}}",
    "refresh_token":"{{refresh_token}}"
  }

If successful, you should get a response in the form of:

{"token_type":"bearer","refresh_token_expires_in":5184000,"refresh_token":"rRxC1nghia8RzJWKWwYMmzWpVcBgMCDY","scope":"","resource_owner":"{{username}}","expires_in":3600,"access_token":"fyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzA4NTgxNDEsImlzcyI6IjJfWXVVVnZWIiwicm9sZXMiOlsiVXNlciJdLCJzY29wZXMiOiIiLCJzdWIiOiJ1c2VyL2tlbm5ldGhqZXJlbXlhdSJ9.0lR6MW9bFcbRiL3RN-U_xHkOS4S9D2JZB1QuCGab2zJ"}

Refreshing the access tokens means that you will obtain a new access token that expires within the time posted above.

Make sure to store your refresh and access tokens securely.

Browser based authentication

Browser based authentication will allow you to act on behalf of any Gfycat user granting you permissions.

Implicit Grant Authentication Flow

The form can be loaded by going to the following url and using the parameters below

Direct user to the form located at: https://gfycat.com/oauth/authorize?client_id={{clientId}} &scope=all &state={{state}} &response_type=token &redirect_uri={{redirectUri}}

We will supply you with a clientId and and a clientSecret with which you may access Gfycat’s API. Each integration should have its own clientId and clientSecret. The clientSecret should be treated like a password and stored securely.

The first step is to acquire a short term authorization code by sending the user to our authorization URL so they can grant access to your integration.

The following paramaters should be included:

Parameter Type Required? Description
client_id string required The clientId we will supply you that identifies your integration.
scope string required The access that your integration is requesting, comma separated. Currently, there is one valid scope value which is all.
state string required Arbitrary text of your choosing, which we will repeat back to you to help you prevent request forgery.
response_type string required For this type of flow the value should be token.
redirect_uri string required The URL where we will send the user after they have completed the login dialog. This field should be URL encoded.

The following scope values are valid:

Scope Description Extended
all Grants basic access to a default scope. No

Integrations are not permitted to request extended scope from users without explicit prior permission from Gfycat. Attempting to request these permissions through the standard user authentication flow will result in an error if extended scope has not been authorized for an integration.

If the user grants your request for access, we will send them back to the specified redirect_uri with an access token in the form of:

https://example.com/callback/{access_token}&token_type=bearer&expires_in={expires_in}&scope={scope}&state={state}

With the following parameters:

Parameter Type Required? Description
access_token string required A long-lived access token.
token_type string required Type of the returned token.
expires_in string required Expiration time of the token from the time of issuing in seconds.
scope string required The scope you have requested.
state string required The state you specified in the request.

If the user declines access, we will send them back to the specified redirect_uri with an error parameter:

https://example.com/callback/error=access_denied&state={state}

Authorization Code Authentication Flow

This flow follows two steps:

The form can be loaded by going to the following url and using the parameters below

Direct user to the form located at: https://gfycat.com/oauth/authorize?client_id={{clientId}} &scope=all &state={{state}} &response_type=code &redirect_uri={{redirectUri}}

We will supply you with a clientId and and a clientSecret with which you may access Gfycat’s API. Each integration should have its own clientId and clientSecret. The clientSecret should be treated like a password and stored securely.

The first step is to acquire a short term authorization code by sending the user to our authorization URL so they can grant access to your integration.

The following paramaters should be included:

Parameter Type Required? Description
client_id string required The clientId we will supply you that identifies your integration.
scope string required The access that your integration is requesting, comma separated. Currently, there is one valid scope value which is all.
state string required Arbitrary text of your choosing, which we will repeat back to you to help you prevent request forgery.
response_type string required The field currently has only one valid value, and should be code.
redirect_uri string required The URL where we will send the user after they have completed the login dialog. This field should be URL encoded.

The following scope values are valid:

Scope Description Extended
all Grants basic access to a default scope. No

Integrations are not permitted to request extended scope from users without explicit prior permission from Gfycat. Attempting to request these permissions through the standard user authentication flow will result in an error if extended scope has not been authorized for an integration.

If the user grants your request for access, we will send them back to the specified redirect_uri with a state and code parameter:

https://example.com/callback/?code={{code}}&state={{state}}

With the following parameters:

Parameter Type Required? Description
code string required A short-lived authorization code that may be exchanged for an access token.
state string required The state you specified in the request.

If the user declines access, we will send them back to the specified redirect_uri with an error parameter:

https://example.com/callback/error=access_denied&state={state}

curl -v -X POST https://api.gfycat.com/v1/oauth/token
-d '{"code":"{code}", "client_id":"{clientId}", "client_secret": "{clientSecret}", "grant_type": "authorization_code","redirect_uri":"{redirectUri}"}'

With the following parameters:

Parameter Type Required? Description
code string required The authorization code you received in the previous step.
client_id string required Your integration’s clientId
client_secret string required Your integration’s clientSecret
grant_type string required The literal string “authorization_code”
redirect_uri string required The same redirect_uri you specified when requesting an authorization code.

If successful, you will receive back an access token response:

{
 "token_type": "Bearer",
 "access_token": {access_token},
 "refresh_token": {refresh_token},
 "scope": {scope},
 "expires_in": {expires_in},
 "refresh_token_expires_in": {refresh_token_expires_in},
 "resource_owner": {resource_owner}
}

Facebook Provider Grant

HTTP Request

POST https://api.gfycat.com/v1/oauth/token

With the facebook provider grant you may decide to authenticate using the facebook auth_code or facebook access_token.

These requests will automatically link the existing accounts with the email that is in their gfycat account and the primary email that is associated with their facebook account.

Provider Grants use the POST request method for data transfer.

We will supply you with a client_id and and a client_secret with which you may access Gfycat’s API. Each integration should have its own client_id and client_secret. The client_secret should be treated like a password and stored securely.

Facebook Auth Code

If you are using an auth_code, your request should look like this:

curl -H "Content-Type: application/json" -v -X POST https://api.gfycat.com/v1/oauth/token -d '{
  "grant_type":"convert_code",
  "provider":"facebook",
  "client_id":"{{client_id}}",
  "client_secret":"{{client_secret}}",
  "auth_code":"{{auth_code}}"
  }'

If successful, you should get a response in the form of:

{"token_type":"bearer","refresh_token_expires_in":3600,"refresh_token":"aPt8fnoTdzVRvIVXOXkvgp703m5dGaXF","scope":"","resource_owner":"soniku","expires_in":3600,"access_token":"eyJhXGciOwJIUzI1NiIsInR5eCI6IkpXVCJ9.eyJleHAiOjE0NTI2MzI4MTAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0znVlLCJpc3MiOiIxXzVmeXdoazR2bWJvazhrc3drdzhvc2ddZ2c4OHd4OHNzMGdnNSNjY3dnazBrOGNrKHNnIiwicmE9ZXMiOlsiVfNlciJdLCJzdWIiOiJ1c2Vyx3NvbmlrdSJ9.6d_TF0Ne8TSE17M8_quekJ-HhFFefwE1l0Q2jasWJ-U"}

Parameters:

Parameter Type Required? Description
grant_type string required This field determines which grant type you are requesting, for the facebook auth code provider grant this value is convert_code.
provider string required This field determines which provider are you using, for the facebook access token provider grant this value is facebook.
client_id string required The client_id we will supply to you that identifies your integration.
client_secret string required The client_secret we will supply to you that identifies your integration.
auth_code string required The auth_code that you have received from facebook.

Responses:

Status code Error code Response
2**
401 InvalidClient The client credentials you provided were invalid
401 InvalidAuthCode The auth code that you have supplied was invalid
401 UnsupportedProvider The provider you have requested is not supported
401 UserNotExists The user with those credentials does not exist
401 AccountLocked This account has been locked, please email contact@gfycat.com to unlock it

The refresh token flow is the same as with the password credentials grant, the access_token that you receive back is a gfycat access token.

You should not expose the refresh token to the public (that includes javascript) since anyone can use refresh tokens to obtain new access tokens.

Facebook Access Tokens

If you have a facebook access token and want to get the gfycat access token, your request should look like:

curl -H "Content-Type: application/json" -v -X POST https://api.gfycat.com/v1/oauth/token -d '{
    "grant_type":"convert_token",
    "provider":"facebook",
    "client_id":"{{client_id}}",
    "client_secret":"{{client_secret}}",
    "token":"{{token}}"
  }'

If successful, you should get a response in the form of:

{"token_type":"bearer","refresh_token_expires_in":3600,"refresh_token":"aPt8fnoTdzVRvIVXOXkvgp703m5dGaXF","scope":"","resource_owner":"soniku","expires_in":3600,"access_token":"eyJhXGciOwJIUzI1NiIsInR5eCI6IkpXVCJ9.eyJleHAiOjE0NTI2MzI4MTAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0znVlLCJpc3MiOiIxXzVmeXdoazR2bWJvazhrc3drdzhvc2ddZ2c4OHd4OHNzMGdnNSNjY3dnazBrOGNrKHNnIiwicmE9ZXMiOlsiVfNlciJdLCJzdWIiOiJ1c2Vyx3NvbmlrdSJ9.6d_TF0Ne8TSE17M8_quekJ-HhFFefwE1l0Q2jasWJ-U"}

Parameters:

Parameter Type Required? Description
grant_type string required This field determines which grant type you are requesting, for the facebook access token provider grant this value is convert_token.
provider string required This field determines which provider are you using, for the facebook access token provider grant this value is facebook.
client_id string required The client_id we will supply to you that identifies your integration.
client_secret string required The client_secret we will supply to you that identifies your integration.
token string required The access token that you have received from facebook.

Responses:

Status code Error code Response
2**
401 InvalidClient The client credentials you provided were invalid
401 InvalidToken The token that you have supplied was invalid
401 UnsupportedProvider The provider you have requested is not supported
401 UserNotExists The user with those credentials does not exist
401 AccountLocked This account has been locked, please email contact@gfycat.com to unlock it

And just as with the auth code, the refresh token flow is the same as with the password credentials grant, the access_token that you receive back is a gfycat aceess token.

You should not expose the refresh token to the public (that includes javascript) since anyone can use refresh tokens to obtain new access tokens.

Twitter Provider Grant

HTTP Request

POST https://api.gfycat.com/v1/oauth/token

With the twitter provider grant you may decide to authenticate using the twitter request token and a verifier or via a twitter token and token secret.

These requests will automatically link the existing accounts with the email that is in their gfycat account and the primary email that is associated with their twitter account.

Provider Grants use the POST request method for data transfer.

We will supply you with a client_id and and a client_secret with which you may access Gfycat’s API. Each integration should have its own client_id and client_secret. The client_secret should be treated like a password and stored securely.

Obtaining a Twitter Request Token

curl -H "Content-Type: application/json" -v -X POST https://api.gfycat.com/v1/oauth/token -d '{
  "grant_type":"request_token",
  "provider":"twitter"
  }'

The response should give you a http status code of 200 and it should look like this {"request_token":"gF0GtAAAAAAAxliHAAABWfp8wzY"}

After obtaining a twitter request token you should direct a user to https://api.twitter.com/oauth/authenticate?oauth_token={{request token}}

That would redirect the user back to gfycat with the verifier.

If you want to redirect user elsewhere you need to obtain the request token for that client from twitter.

Obtaining Gfycat Access Token from Twitter Request Token and Verifier

If you are using a request token and verifier, your request should look like this:

curl -H "Content-Type: application/json" -v -X POST https://api.gfycat.com/v1/oauth/token -d '{
  "grant_type":"convert_request_token",
  "provider":"twitter",
  "client_id":"{{client_id}}",
  "client_secret":"{{client_secret}}",
  "token":"{{token}}",
  "verifier":"{{verifier}}"
  }'

If successful, you should get a response in the form of:

{"token_type":"bearer","refresh_token_expires_in":3600,"refresh_token":"aPt8fnoTdzVRvIVXOXkvgp703m5dGaXF","scope":"","resource_owner":"soniku","expires_in":3600,"access_token":"eyJhXGciOwJIUzI1NiIsInR5eCI6IkpXVCJ9.eyJleHAiOjE0NTI2MzI4MTAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0znVlLCJpc3MiOiIxXzVmeXdoazR2bWJvazhrc3drdzhvc2ddZ2c4OHd4OHNzMGdnNSNjY3dnazBrOGNrKHNnIiwicmE9ZXMiOlsiVfNlciJdLCJzdWIiOiJ1c2Vyx3NvbmlrdSJ9.6d_TF0Ne8TSE17M8_quekJ-HhFFefwE1l0Q2jasWJ-U"}

Parameters:

Parameter Type Required? Description
grant_type string required This field determines which grant type you are requesting, for the twitter auth code provider grant this value is provider_token.
provider string required This field determines which provider are you using, for the twitter provider token grant this value is twitter.
client_id string required The client_id we will supply to you that identifies your integration.
client_secret string required The client_secret we will supply to you that identifies your integration.
token string required The request token that you have received from twitter.
verifier string required The token verifier that you have received from twitter.

Responses:

Status code Error code Response
2**
401 InvalidClient The client credentials you provided were invalid
401 InvalidToken The token code that you have supplied was invalid
401 UnsupportedProvider The provider you have requested is not supported
401 UserNotExists The user with those credentials does not exist
401 AccountLocked This account has been locked, please email contact@gfycat.com to unlock it

The refresh token flow is the same as with the password credentials grant, the access_token that you receive back is a gfycat access token.

You should not expose the refresh token to the public (that includes javascript) since anyone can use refresh tokens to obtain new access tokens.

Obtaining Gfycat Access Token from Twitter Oauth Token and Twitter Oauth Token Secret

If you are using a request token and verifier, your request should look like this:

curl -H "Content-Type: application/json" -v -X POST https://api.gfycat.com/v1/oauth/token -d '{
  "grant_type":"convert_token",
  "provider":"twitter",
  "client_id":"{{client_id}}",
  "client_secret":"{{client_secret}}",
  "token":"{{token}}",
  "tokenSecret":"{{tokenSecret}}"
  }'

If successful, you should get a response in the form of:

{"token_type":"bearer","refresh_token_expires_in":3600,"refresh_token":"aPt8fnoTdzVRvIVXOXkvgp703m5dGaXF","scope":"","resource_owner":"soniku","expires_in":3600,"access_token":"eyJhXGciOwJIUzI1NiIsInR5eCI6IkpXVCJ9.eyJleHAiOjE0NTI2MzI4MTAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0znVlLCJpc3MiOiIxXzVmeXdoazR2bWJvazhrc3drdzhvc2ddZ2c4OHd4OHNzMGdnNSNjY3dnazBrOGNrKHNnIiwicmE9ZXMiOlsiVfNlciJdLCJzdWIiOiJ1c2Vyx3NvbmlrdSJ9.6d_TF0Ne8TSE17M8_quekJ-HhFFefwE1l0Q2jasWJ-U"}

Parameters:

Parameter Type Required? Description
grant_type string required This field determines which grant type you are requesting, for the twitter auth code provider grant this value is provider_token.
provider string required This field determines which provider are you using, for the twitter provider token grant this value is twitter.
client_id string required The client_id we will supply to you that identifies your integration.
client_secret string required The client_secret we will supply to you that identifies your integration.
token string required The request token that you have received from twitter.
secret string required The token secret that you have received from twitter.

Responses:

Status code Error code Response
2**
401 InvalidClient The client credentials you provided were invalid
401 InvalidToken The token code that you have supplied was invalid
401 UnsupportedProvider The provider you have requested is not supported
401 UserNotExists The user with those credentials does not exist
401 AccountLocked This account has been locked, please email contact@gfycat.com to unlock it

The refresh token flow is the same as with the password credentials grant, the access_token that you receive back is a gfycat access token.

You should not expose the refresh token to the public (that includes javascript) since anyone can use refresh tokens to obtain new access tokens.

Users

Checking if the username is available / username exists / username is valid

curl -v -X HEAD https://api.gfycat.com/v1/users/randomuser --header "Authorization: Bearer <<insert token here>>"

The above command returns an HTTP response like this:

HTTP/1.1 404 Not Found
Content-Length: 0
Connection: keep-alive

HTTP Request

HEAD https://api.gfycat.com/v1/users/{username}

Status codes and their meaning:

Status code Description
404 Not Found The username was not found which means that it is available.
422 Unprocessable Entity The username was invalid.
2** No Content The username was found which means that the username is unavailable.
401 Unauthorized You need to provide a valid token to perform this action

Checking if users email is verified or not

You must have a valid gfycat token in order to perform this request.

HTTP Request

GET https://api.gfycat.com/v1/me/email_verified

Status code Description
404 Not Found The email attached to the token bearer’s username is not verified.
2** No Content The email attached to the token bearer’s username is verified.
401 Unauthorized You need to provide a valid token to perform this action
curl -v -X GET https://api.gfycat.com/v1/me/email_verified --header "Authorization: Bearer <<insert token here>>"

Sending an email verification request

HTTP Request

POST https://api.gfycat.com/v1/me/send_verification_email

Responses:

Status code Error code Response
2**
400 Error Unable to send verification email
404 NotFound Sorry, that user does not have an email address registered.
401 You need to provide a valid token to perform this action
curl -v -X POST https://api.gfycat.com/v1/me/send_verification_email --header "Authorization: Bearer <<insert token here>>"

Send a password reset email

HTTP Request

PATCH https://api.gfycat.com/v1/users

JSON data:

Parameter Type Description
value string User’s username or email
action string The action to perform. For sending a password reset email, this value is ‘send_password_reset_email’

Responses:

Status code Error code Response
2**
400 BadParameter action not recognized
400 MissingParameter action is a required parameter
400 MissingParameter value is a required parameter
404 NotFound We don’t have that username or email at GfyCat or email does not exist for this user
422 MaximumTriesExceeded You have exceeded the maximum amount of reset attempts
422 NoEmailAssociated Sorry, that user does not have an email address registered
400 Error Unable to send reset password email
401 Unauthorized
curl -H "Content-Type: application/json" -v -X PATCH https://api.gfycat.com/v1/users --header "Authorization: Bearer <<insert token here>>" -d '{"action":"send_password_reset_email","value":"soniku"}'

Getting the user’s public details

HTTP Request

GET https://api.gfycat.com/v1/users/{userid}

The response is a JSON array with the following keys:

Field Type Description
userid string A unique identifier for the user.
username string The user’s username on Gfycat.
description string The user’s profile description.
profileUrl string The user’s profile link.
name string The user’s name on Gfycat.
views integer The number of user’s gfy views on Gfycat.
emailVerified boolean The user’s email verification status.
url string The URL to the user’s profile on Gfycat
createDate integer The unix timestamp of the date the user created their account
profileImageUrl string The URL to the user’s avatar on Gfycat
verified boolean The account’s verified status.
followers integer The number of user’s followers.
following integer The number of users this user follows.

Possible errors:

Error code Description
401 Unauthorized The accessToken is invalid or has been revoked.
curl -v -X GET https://api.gfycat.com/v1/users/user{userid} --header "Authorization: Bearer <<insert token here>>"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
   "username": "jimmy",
   "emailVerified": false,
   "uploadNotices": false,
   "url": "https://gfycat.com/@jimmy",
   "createDate": "1374869644"
}

Getting the authenticated user’s details

HTTP Request

GET https://api.gfycat.com/v1/me

The response is a JSON array with the following keys:

Field Type Description
userid string A unique identifier for the user.
username string The user’s username on Gfycat.
email string The user’s email on Gfycat.
description string The user’s profile description.
profileUrl string The user’s profile link.
name string The user’s name on Gfycat.
views integer The number of user’s gfy views on Gfycat.
uploadNotices boolean The user’s upload notices settings, whether the user wants to get notified of uploads or not.
emailVerified boolean The user’s email verification status.
url string The URL to the user’s profile on Gfycat
createDate integer The unix timestamp of the date the user created their account
profileImageUrl string The URL to the user’s avatar on Gfycat
verified boolean The account’s verified status.
followers integer The number of user’s followers.
following integer The number of users this user follows.
geoWhitelist string The user’s geo whitelist on Gfycat.
domainWhitelist string The user’s domain whitelist on Gfycat.
associatedProviders string The user’s associated provider details (has the user linked their facebook or twitter account and selected details from the provider)
iframeProfileImageVisible boolean The user’s profile image visibility on the iframe

Possible errors:

Error code Description
401 Unauthorized The accessToken is invalid or has been revoked.
curl -v -X GET https://api.gfycat.com/v1/me --header "Authorization: Bearer <<insert token here>>"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "userid": "jimmy",
    "email": "jimmy@gmail.com",
    "name": "Jimmy",
    "username": "jimmy",
    "canonicalUsername": "jimmy",
    "views": "0",
    "uploadNotices": false,
    "createDate": "1374869644",
    "emailVerified": false,
    "verified": false,
    "followers": "0",
    "following": "0",
    "publishedGfycats": "0",
    "totalGfycats": "1",
    "totalBookmarks": "0",
    "totalAlbums": "0",
    "publishedAlbums": "0",
    "iframeProfileImageVisible": false,
    "domainWhitelist": [],
    "geoWhitelist": [],
    "url": "https://gfycat.com/@jimmy"
}

Updating user’s details

HTTP Request

PATCH https://api.gfycat.com/v1/me

curl -v -X PATCH https://api.gfycat.com/v1/me --header "Authorization: Bearer <<insert token here>>" -d '{"operations":[{"op":"add","path":"/profile_url","value":"http://www.google.com"},{"op":"add","path":"/email","value":"youremail@gfycat.com"}]}'

The data sent with a patch request is in the format of : {"operations":[{"op":"add","path":"/profile_url","value":"http://www.google.com"},{"op":"add","path":"/email","value":"youremail@gfycat.com"}]}

Where each operation follows the structure of: {"op":"<<operation name>>","path":"<<path to update>>","value":"<<value for the operation>>"}

Supported operations currently are add, remove and replace.

The whitelists require for the parameter to be an array in the form of: "value":["us", "ca"] Remove does not require a value parameter.

Valid operation/path combinations:

Path Operations allowed
/name add, remove
/email add, remove
/password add
/profile_url add, remove
/description add, remove
/upload_notices add
/domain_whitelist replace
/geo_whitelist replace
/iframe_image_visible replace

Upon a successful request, you should receive a response with a 204 status.

The responses are listed in the table below:

Status code Error code Responses
2**
400 BadParameter operations parameter should be an array of json operations
400 BadParameter Domain whitelist should be an array of non-empty strings
400 BadParameter Geo whitelist should be an array of non-empty 2 letter strings
400 MissingParameter Operations is a required parameter
400 InvalidOperation Operation not supported
400 InvalidIframePermissions This user does not have permissions to set profile image visibility
400 InvalidPath The path that you have requested is invalid
400 InvalidName Name should be from 1 to 80 characters long
400 InvalidNotices Upload notices should be either 0 or 1
400 InvalidIframeVisibility Value parameter should be either 0 or 1
400 InvalidUrl The url that you have provided was not valid
400 InvalidDescription Description should be from 1 to 150 characters long
400 EmailTaken We already have that email registered
400 InvalidEmail The email that you have provided is invalid
400 InvalidPassword Password too short. Minimum length is 4 characters
400 InvalidPassword Password too long. Maximum length is 64 characters
400 Error Unable to update profile url
400 Error Unable to update name
400 Error Unable to set upload notifications
400 Error Unable to update description
400 Error Unable to update email
400 Error Unable to update password
400 Error Error updating properties
401 Unauthorized

Linking the provider account to the existing gfycat account

HTTP Request

POST https://api.gfycat.com/v1/me/providers

curl -v -X POST https://api.gfycat.com/v1/me/providers -d '{"provider":"{{name of provider}}","token":"{{token}}","verifier":"{{verifier}}"}' --header "Authorization: Bearer <<insert token here>>"

Upon a successful request, you should receive a response with a 2** status response.

Currently the only supported external provider is twitter.

Twitter’s token and verifiers are single use only so subsequent calls upon success would require new token/verifier combination.

Parameter Type Description
token string Twitter’s request token for which the verifier was obtained
verifier string Twitter’s verifier value
secret string (optional, use either secret or token and verifier) If you have attempted to login with Twitter previously and obtained a secret, use it here to not have to reauthenticate with Twitter

The responses are listed in the table below:

Status code Error code Responses
2**
400 AccountAlreadyLinked This twitter account was already linked
400 MissingParameter Missing Provider
400 InvalidParameter Unknown Provider
400 MissingParameter verifier is required
400 InvalidParameter Invalid secret
400 MissingParameter secret or token and verifer are required
400 InvalidParameter The request should be in json format.
400 TwitterException Exception communicating with Twitter, try again later
401 InvalidTwitterCredentials Invalid twitter token or verifier
401 Unauthorized User is not authorized to perform this action

HTTP Request

POST https://api.gfycat.com/v1/me/providers

curl -v -X DELETE https://api.gfycat.com/v1/me/providers/{{provider name}} --header "Authorization: Bearer <<insert token here>>"

Upon a successful request, you should receive a response with a 2** status response.

Currently the only supported external provider is twitter.

The responses are listed in the table below:

Status code Error code Responses
2**
400 ProviderLinkNotFound User’s link was not found for this provider
401 Unauthorized User is not authorized to perform this action

Updating user’s whitelists

There are 2 user’s whitelists, domain whitelist and geo whitelist.

User’s domain whitelist controls which domains are allowed to embed user’s gfycats.

User’s geo whitelist controls which countries would be able to view user’s embeds.

By default, all domains are allowed to embed this user’s gfycats and all the gfycats would default to appear in all countries possible unless specified here.

The embedding whitelists can also be specified per individual gfycat, for details on that, see updating gfycats.

HTTP Requests

GET https://api.gfycat.com/v1/me/domain-whitelist

PUT https://api.gfycat.com/v1/me/domain-whitelist

DELETE https://api.gfycat.com/v1/me/domain-whitelist

GET https://api.gfycat.com/v1/me/geo-whitelist

PUT https://api.gfycat.com/v1/me/geo-whitelist

DELETE https://api.gfycat.com/v1/me/geo-whitelist

curl -v -X PUT https://api.gfycat.com/v1/me/domain-whitelist -d '{"domainWhitelist":["domain1","domain2"]}' --header "Authorization: Bearer <<insert token here>>"
curl -v -X GET https://api.gfycat.com/v1/me/domain-whitelist --header "Authorization: Bearer <<insert token here>>"
curl -v -X DELETE https://api.gfycat.com/v1/me/domain-whitelist --header "Authorization: Bearer <<insert token here>>"
curl -v -X PUT https://api.gfycat.com/v1/me/geo-whitelist -d '{"geoWhitelist":["us","ca"]}' --header "Authorization: Bearer <<insert token here>>"
curl -v -X GET https://api.gfycat.com/v1/me/geo-whitelist --header "Authorization: Bearer <<insert token here>>"
curl -v -X DELETE https://api.gfycat.com/v1/me/geo-whitelist --header "Authorization: Bearer <<insert token here>>"

To update/get user’s whitelists you need to issue a request to one of the paths below

Path Method Description
/v1/me/domain-whitelist PUT Update/replace the user’s domain whitelist. Params: 'domainWhitelist’ (array)
/v1/me/domain-whitelist GET Get the user’s domain whitelist.
/v1/me/domain-whitelist DELETE Remove the user’s domain whitelist.
/v1/me/geo-whitelist PUT Update/replace the user’s geo whitelist. Params: 'geoWhitelist’ (array)
/v1/me/geo-whitelist GET Get the user’s geo whitelist.
/v1/me/geo-whitelist DELETE Remove the user’s geo whitelist.

Uploading user’s profile image

To upload a user’s image you need to:

  1. Obtain an upload url
  2. Upload the image to a url that you get from an endpoint (optional: checking the status of your image upload)

1. Obtaining an upload url

HTTP Request

POST https://api.gfycat.com/v1/me/profile_image_url

curl -v -X POST https://api.gfycat.com/v1/me/profile_image_url --header "Authorization: Bearer <<insert token here>>"

The response from the endpoint should contain a url where you can upload an image to.

The last part of the url is your upload ticket.

Example: https://imageupload.gfycat.com/{ticket}

2. Upload the image to a url that you get from an endpoint

curl -XPUT -T yourfile https://imageupload.gfycat.com/{ticket}'

After you obtain the url you can upload the image to the location provided.

Once the upload is successfully processed, the image should become available as a part of your profile information.

Checking the status of your image upload

HTTP Request

GET https://api.gfycat.com/v1/me/profile_image_url/status/{ticket}

curl -v -X GET https://api.gfycat.com/v1/me/profile_image_url/status/{ticket} --header "Authorization: Bearer <<insert token here>>"

Upon a successful request, you should receive a response with a 200 status and a response of either pending or succeeded.

The responses are listed in the table below:

Status code Error code Responses
2**
400 ImageUploadFailed Upload failed, did you upload an image?
400 Error Unable to retrieve the upload ticket status
404 NotFound Ticket status not found

Creating a new user account

curl -H "Content-Type: application/json" -v -X POST https://api.gfycat.com/v1/users --header "Authorization: Bearer <<insert token here>>" -d '{"username":"testusername","password":"somepassword","provider":"facebook","email":"test@gfycat.com","auth_code":"<<insert facebook auth code here>>"}'
{"token_type":"bearer","refresh_token_expires_in":3600,"refresh_token":"aPt8fnoTdzVRvIVXOXkvgp703m5dGaXF","scope":"","resource_owner":"soniku","expires_in":3600,"access_token":"eyJhXGciOwJIUzI1NiIsInR5eCI6IkpXVCJ9.eyJleHAiOjE0NTI2MzI4MTAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0znVlLCJpc3MiOiIxXzVmeXdoazR2bWJvazhrc3drdzhvc2ddZ2c4OHd4OHNzMGdnNSNjY3dnazBrOGNrKHNnIiwicmE9ZXMiOlsiVfNlciJdLCJzdWIiOiJ1c2Vyx3NvbmlrdSJ9.6d_TF0Ne8TSE17M8_quekJ-HhFFefwE1l0Q2jasWJ-U"}

HTTP Request

POST https://api.gfycat.com/v1/users

The POST must include a JSON object with the user details. The following combinations of parameters are valid:

Valid parameter combinations
username, password
username, password, email
username, provider, auth_code
username, provider, access_token
username, provider, token
username, provider, verifier
username, provider, oauth_token
username, provider, oauth_token_secret
username, provider, secret
username, password, provider, auth_code
username, password, provider, access_token
username, password, provider, token
username, password, provider, verifier
username, password, provider, oauth_token
username, password, provider, oauth_token_secret
username, password, provider, secret
username, email, provider, auth_code
username, email, provider, access_token
username, email, provider, token
username, email, provider, verifier
username, email, provider, oauth_token
username, email, provider, oauth_token_secret
username, email, provider, secret
username, password, email, provider, auth_code
username, password, email, provider, access_token
username, password, email, provider, token
username, password, email, provider, verifier
username, password, email, provider, oauth_token
username, password, email, provider, oauth_token_secret
username, password, email, provider, secret

The responses are listed in the table below

Status code Error code Responses
2**
400 InvalidUsername Username too short. Minimum length is 6 characters
400 InvalidUsername Username too long. Maximum length is 20 characters
400 InvalidPassword Password too short. Minimum length is 4 characters
400 InvalidPassword Password too long. Maximum length is 64 characters
400 InvalidUsername Letters, numbers, or .-_ are valid
400 MissingParameter Username not provided
400 MissingParameter Password not provided
400 MissingParameter verifier is required
400 EmailTaken We already have that email registered
400 UsernameTaken That username is taken
400 InvalidEmail Email validation failed
400 InvalidAuthCode Invalid auth_code
400 InvalidAccessToken Invalid access_token
400 MissingParameter Auth code provided without a provider
400 MissingParameter Access token provided without a provider
400 BadParameter Unsupported provider
400 AlreadyLinked Account already linked
400 InvalidToken Invalid oauth_token or oauth_token_secret
400 InvalidAccessToken Invalid access_token
400 InvalidCredentials Invalid token or verifier
400 Error Account could not be created
401 Unauthorized The secret is not valid or expired
404 NotFound Unable to obtain facebook token
503 ServiceNotAvailable Unable to obtain gfycat token
401 Unauthorized

The Bad Request code (400):

If unsuccessful, you should receive a http 400 status code in the form of:

{"errorMessage":{"code":"MissingParameter","description":"Password not provided"}}

Following another user

curl -XPUT https://api.gfycat.com/v1/me/follows/<<other_user>> --header "Authorization: Bearer <<insert token here>>"

HTTP Request

PUT https://api.gfycat.com/v1/me/follows/{other_user}

Unfollowing a user

curl -XDELETE https://api.gfycat.com/v1/me/follows/<<other_user>> --header "Authorization: Bearer <<insert token here>>"

HTTP Request

DELETE https://api.gfycat.com/v1/me/follows/{other_user}

Checking if you follow a user

curl -XHEAD https://api.gfycat.com/v1/me/follows/<<other_user>> --header "Authorization: Bearer <<insert token here>>"

HTTP Request

HEAD https://api.gfycat.com/v1/me/follows/{other_user}

The response to this request will be either 200 (you follow the other user) or 404 (you do not follow this user).

Listing all users you follow

curl -XGET https://api.gfycat.com/v1/me/follows --header "Authorization: Bearer <<insert token here>>"

HTTP Request

GET https://api.gfycat.com/v1/me/follows

Note: Response is limited to 500 followers

Listing all users following you

curl -XGET https://api.gfycat.com/v1/me/followers --header "Authorization: Bearer <<insert token here>>"

HTTP Request

GET https://api.gfycat.com/v1/me/followers

Note: Response is limited to 500 followers

User Feeds

Listing the the feed of published gfycats for a user

curl -v -X GET https://api.gfycat.com/v1/users/someuser/gfycats
{
   "contents":[
      {
         "gfyId":"yellowidenticaleuropeanpolecat",
         "gfyNumber":"444093595",
         "webmUrl":"http://zippy.gfycat.com/YellowIdenticalEuropeanpolecat.webm",
         "gifUrl":"http://giant.gfycat.com/YellowIdenticalEuropeanpolecat.gif",
     "mobileUrl":"https://thumbs.gfycat.com/YellowIdenticalEuropeanpolecat-mobile.mp4",
         "mobilePosterUrl":"https://thumbs.gfycat.com/YellowIdenticalEuropeanpolecat-mobile.jpg",
         "posterUrl":"https://thumbs.gfycat.com/YellowIdenticalEuropeanpolecat-poster.jpg",
         "thumb100PosterUrl":"https://thumbs.gfycat.com/YellowIdenticalEuropeanpolecat-thumb100.jpg",
         "max5mbGif":"https://thumbs.gfycat.com/YellowIdenticalEuropeanpolecat-size_restricted.gif",
         "max2mbGif":"https://thumbs.gfycat.com/YellowIdenticalEuropeanpolecat-small.gif",
         "width":446,
         "height":258,
         "frameRate":10,
         "numFrames":70,
         "mp4Size":328736,
         "webmSize":198586,
         "gifSize":4534598,
         "createDate":"1406737716",
         "nsfw":"0",
         "mp4Url":"http://zippy.gfycat.com/YellowIdenticalEuropeanpolecat.mp4",
         "likes":0,
         "published":1,
         "dislikes":0,
         "extraLemmas":"",
         "md5":"d73d02f6cb22bd59cd1041decbc06d2f",
         "views":91,
         "tags":null,
         "userName":"jimmy",
         "gfyName":"YellowIdenticalEuropeanpolecat",
         "title":"Untitled",
         "description":""
      },
      {
         "gfyId":"yellowcaninegiraffe",
         "gfyNumber":"444026702",
         "webmUrl":"http://zippy.gfycat.com/YellowCanineGiraffe.webm",
         "gifUrl":"http://giant.gfycat.com/YellowCanineGiraffe.gif",
         "mobileUrl":"https://thumbs.gfycat.com/YellowCanineGiraffe-mobile.mp4",
         "mobilePosterUrl":"https://thumbs.gfycat.com/YellowCanineGiraffe-mobile.jpg",
         "posterUrl":"https://thumbs.gfycat.com/YellowCanineGiraffe-poster.jpg",
         "thumb100PosterUrl":"https://thumbs.gfycat.com/YellowCanineGiraffe-thumb100.jpg",
         "max5mbGif":"https://thumbs.gfycat.com/YellowCanineGiraffe-size_restricted.gif",
         "max2mbGif":"https://thumbs.gfycat.com/YellowCanineGiraffe-small.gif",
         "width":402,
         "height":226,
         "frameRate":25,
         "numFrames":336,
         "mp4Size":1587531,
         "webmSize":688829,
         "gifSize":5879972,
         "createDate":"1442433252",
         "nsfw":"0",
         "mp4Url":"http://fat.gfycat.com/YellowCanineGiraffe.mp4",
         "likes":0,
         "published":"1",
         "dislikes":0,
         "extraLemmas":"",
         "md5":"36bb49eda6834a70c15bbc39403b8fed",
         "views":2,
         "tags":null,
         "userName":"jimmy",
         "gfyName":"YellowCanineGiraffe",
         "title":"F Small",
         "description":""
      }
   ],
   "cursor":"bm9uY2V8eyJ1c2VyRm9sZGVySWQiOnsiUyI6ImplZmZyZXl8MSJ9LCJnZnlJZCI6eyJTIjoid2luZGluZ3ZhZ3VlZGFzc2llcmF0In0sInVzZXJJZCI6eyJTIjoiamVmZnJleSJ9fQ=="
}

HTTP Request

GET https://api.gfycat.com/v1/users/{userId}/gfycats

Returns a full list of Gfycats that the user has published. This endpoint offers a set of data similar to what you’ll see at https://gfycat.com/@username.

Resource HTTP Verb Description
/v1/users/{userId}/gfycats GET Request a list of the user’s gfycats, in descending order from the newest. Parameters: count, cursor

The response is a list of gfycat objects. An empty array is returned if user doesn’t have gfycats published. The response array is wrapped in an envelope labelled “gfycats”.

Field Type Description
content JSON Array A list of gfycat items
cursor string A cursor used to retrieve the next page of results

If the user does not have any gfycats/does not exist or we are at the end of a feed the cursor would be empty.

Example of the empty cursor response:

{"cursor":"","gfycats":[]}

Listing the the private feed of all gfycats for a user

curl -v -X GET https://api.gfycat.com/v1/me/gfycats

HTTP Request

GET https://api.gfycat.com/v1/me/gfycats

Returns a full list of all Gfycats in the users account, published or not. See the “public” feed above for details. Note that this endpoint is only available to the authenticating user.

See also the folders resources. Each Gfycat in this feed will also appear in exactly one folder, as organized within the users account.

Listing the timeline feed of all users you follow

curl -v -X GET https://api.gfycat.com/v1/me/follows/gfycats -H "Authorization: Bearer <<token>>"

HTTP Request

GET https://api.gfycat.com/v1/me/follows/gfycats

Returns a timeline list of all published Gfycats in the users you follow. See the “public” feed above for details. Note that this endpoint is only available to the authenticating user.

User Folders

curl -iX PUT https://api.gfycat.com/users/jimmy/private/folders/5083aacd558b0bd4653ee4b125d11217/name?folderName='New Name'
HTTP/1.1 204 No Content
Date: Tue, 08 Dec 2015 07:22:58 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Cache-Control: private

The responses for successful PUT commands will be HTTP 204 No Content.

HTTP Requests

The following resources are available for user folders. The URI space for folders is /v1/me/folders. All actions available for folders are also available for bookmark-folders and album-folders /v1/me/album-folders and /v1/me/bookmark-folders.

Resource HTTP Verb Description
/v1/me/folders GET Get a JSON formatted array of all folders in the user account, as a nested tree.
/v1/me/folders/{folderId} GET Get contents of the given folder. This will include fields name, count, and contents. “contents” will be an array of items: gfycats, for folder and bookmark-folders; albums for album-folders.
/v1/me/folders/{folderId} DELETE Delete a folder (must be empty)
/v1/me/folders/{folderId}/name GET Get the name of a folder
/v1/me/folders/{folderId}/name PUT Change the name of a folder. Requires parameter “value” with the name of the new folder.
/v1/me/folders/{folderId} PUT Move a folder (and contents) to a new location in the tree. Requires parameter parentId
/v1/me/folders/{folderId} PATCH Move some of the gfycats within a folder to another folder. Requires parameter action to be set to move_contents, parent_id and gfy_ids. gfy_ids must be a JSON array of the gfycatIds, or albumIds to move.
/v1/me/folders/{folderId} or /v1/me/folders POST Create a new folder. Requires parameter folderName The new folder will be inside folderId, if supplied

Error example:

{
  "errorMessage":
    {
      "code": "MissingParameter",
      "description":"folderName is a required parameter."
    }
}

Possible errors:

Error code Description
400 Bad Request Required fields were invalid, or missing.
401 Unauthorized The access token is invalid or has been revoked.
403 Forbidden The clientId does not have permission, or the userId in the request path points to wrong/non-existent user.

Other errors for 400 Bad Request may return additional information in the JSON respose. Errors will be wrapped in an “errorMessage” envelope, and include code and description.

Bookmarks

Users can bookmark and unbookmark any public Gfycat, with or without specifying the folder. The responses and interactions will follow the user folder examples above. The following resources are used for bookmark actions:

Resource HTTP Verb Description
/v1/me/bookmark-folders GET Get a JSON formatted array of all bookmarks, as a nested tree.
/v1/me/bookmark-folders/{bookmarkFolderId} GET Get bookmark contents for the logged in user
/v1/me/bookmarks/{gfyId} GET Determines if the authenticated user has bookmarked a Gfycat. Returns bookmarkState='1’ or '0’
/v1/me/bookmarks/{gfyId} PUT Bookmarks the given Gfycat for the user
/v1/me/bookmark-folders/{folderId}/contents/{gfyId} PUT Bookmarks the given Gfycat for the user
/v1/me/bookmark-folders/{folderId}/contents/{gfyId} DELETE Unbookmarks the given Gfycat for the user
/v1/me/bookmark-folders/{folderId} PATCH Required parameter: action to be set to move_contents. Moves contents from one bookmark folder to another, required parameters: gfy_ids, parent_id.
/v1/me/bookmarks/{gfyId} DELETE Un-bookmarks the given Gfycat for the user

Albums

Albums resources can read and update album description, title, contents, and album order:

Resource HTTP Verb Description
/v1/me/album-folders GET Get a JSON formatted array of all albums, as a nested tree.
/v1/users/{userId}/albums/{albumId} GET Get album contents available (public)
/v1/users/{userId}/album_links/{link_text} GET Get album contents by link text (public)
/v1/me/albums/{albumId} GET Get album contents for the logged in user
/v1/me/albums/{albumId} POST Create a new album
/v1/me/albums/{albumId} PUT Move album to an album folder. Required parameter: 'parentId’
/v1/me/albums/{albumId} PATCH Perform actions on the album or its contents. Possible actions are: add_to_album,move_contents and remove_contents. Remove a gfycat(s) from an album. Required parameter: “action”, “contents” (array of gfyId’s). Move album contents from one album to another. Parameters: action should be set to move_contents,“parent_id” (id of the album you are moving the contents to), “gfy_ids” (array of gfyId’s). add_to_album Add a gfycat(s) to an album. Required parameter: “gfy_ids” (array of gfyId’s)
/v1/me/album-folders/{folderId} POST Create an album within a folder. Parameters: title,description,contents
/v1/me/albums/{albumId}/title PUT Parameters: “value”
/v1/me/albums/{albumId}/description PUT Parameters: “value”
/v1/me/albums/{albumId}/nsfw PUT Parameters: “value”={0,1,3}. 0 for clean, 1 for adult, or 3 for potentially offensive.
/v1/me/albums/{albumId}/published PUT Parameters: “value”={0,1}. 1 published, 0 for not published
/v1/me/albums/{albumId}/order PUT Parameters: “newOrder”. PUT an array of gfycat ids, arranged in the new order that the album should follow

Getting Gfycats

Getting info for a single gfycat

curl -v -X GET https://api.gfycat.com/v1/gfycats/{gfyid}  -H "Authorization: Bearer <<token>>"

GET https://api.gfycat.com/v1/gfycats/{gfyid}

Make a call to the endpoint using either the client or a user token.

If successful you should get a response with a status of 200 and the response should look like this:

{"gfyItem": {"gfyId":"{gfyid}","gfyName":"{gfyname}","gfyNumber":"{gfynumber}","webmUrl":"", "gifUrl":"","mobileUrl":"","mobilePosterUrl":"","miniUrl":"","miniPosterUrl":"", "posterUrl":"","thumb100PosterUrl":"", "max5mbGif":"","max2mbGif":"","max1mbGif":"","gif100px":"","width":0, "height":0,"avgColor":"#000000","frameRate":1,"numFrames":1,"mp4Size":1,"webmSize":1, "gifSize":1,"source":1,"createDate":1,"nsfw":"0","mp4Url":"","likes":"0","published":1, "dislikes":"0","extraLemmas":"","md5":"0","views":0,"tags":[""],"userName":"anonymous", "title":"","description":"","languageText":"","languageCategories":null,"subreddit":"", "redditId":"","redditIdText":"","domainWhitelist":[]}}

Otherwise if a gfycat is not found, you should get a status of 404 with a response of:

{"errorMessage":"{gfyname} does not exist."}

Creating Gfycats

Fetching a remote url to create a new gfycat

        curl -v -XPOST -d '{"fetchUrl":"https://somevideo.somesite.com/video.mp4","title":"This is a title"}' https://api.gfycat.com/v1/gfycats

HTTP Request

POST https://api.gfycat.com/v1/gfycats

Required POST data:

Parameter Description
fetchUrl Url to retrieve and turn into a gfycat

The response from calling this endpoint would give you a gfyname, however the gfycat will not be created if the content that you upload is detected to be already existing on gfycat. If you want this check to not be performed and create the gfycat anyway, then include a noMd5 property to this request.

See below for a full list of properties.

Checking the status of your upload

GET https://api.gfycat.com/v1/gfycats/fetch/status/gfyname

The response of calling the status endpoint would look like this:

Response while encoding: {task: "encoding", time: 10}

Response when complete: {"task":"complete","gfyname":"yourgfyname"}

Response when not found: {"task":"NotFoundo","time":10}

Response when an error occurs during encoding: {"task": "error", "errorMessage": {"code": "error code", "description": "error description"}}

If the duplicate is found then the response from the status endpoint would return the properties of the original file with the property “md5Found”:1

The response in that case might have these properties:

“gfyId”, “gfyName”, “gfyNumber”, “webmUrl”, “gifUrl”, “mobileUrl”, “mobilePosterUrl”, “posterUrl”, “thumb100PosterUrl”, “max5mbGif”, “max2mbGif”, “width”, “height”, “avgColor”, “frameRate”, “numFrames”, “mp4Size”, “webmSize”, “gifSize”, “source”, “createDate”, “nsfw”, “mp4Url”, “likes”, “published”, “dislikes”, “extraLemmas”, “md5”, “views”, “tags”, “userName”, “title”, “description”, “languageCategories”, “task”, “gfyname”, “md5Found”

Uploading a file to create a new gfycat

    curl -v -XPOST https://api.gfycat.com/v1/gfycats -H "Content-Type: application/json"

Response:

{
  "gfyname": "GeneralSillyAvians"
}
    curl -i https://filedrop.gfycat.com --upload-file ./WeightyGlitteringJavalina

    curl -v -XPOST -H "Content-Type: application/json" -d '{"title":"This is a title"}' https://api.gfycat.com/v1/gfyc
ats

HTTP Request

POST https://api.gfycat.com/v1/gfycats

Uploading a file to convert involves two steps:

See below for all available options

Gfycat creation parameters and options

curl -v -X POST https://api.gfycat.com/v1/gfycats -d '{
  "fetchUrl": "https://giant.gfycat.com/DetailedFearfulBangeltiger.mp4",
  "fetchMinutes": 2,
  "noMd5" : "true",
  "captions": [
      {
        "startSeconds":0,
        "duration": 14,
        "text":"caption",
        "fontHeightRelative": 50,
        "xRelative": 20,
        "yRelative":50
      }
    ]
}' -H 'Content-Type: application/json'

The following is an example POST object:

{
  "fetchUrl": "https://giant.gfycat.com/DetailedFearfulBangeltiger.mp4",
  "title": "This is a title",
  "noMd5" : "true",
  "captions": [
      {
        "startSeconds":0,
        "duration": 2,
        "text":"a caption",
        "fontHeight": 35
      }
    ]
}

Response:

{
  "gfyname": "GeneralSillyAvians"
}

POST parameters:

Parameter Conditional Description
fetchUrl Optional url to fetch and convert
title Optional Title
description Optional Description
tags Optional JSON array of strings to use as tags
noMd5 Optional Boolean, send this flag if you want to ignore the md5 check and create a duplicate if the same gfycat is found
private Optional Indicates if content should be published or not– Boolean 1 or 0
nsfw Optional Indicates if content is “safe for work” or not. 0 == Clean, 1 == Adult 3 == Possibly Offensive
fetchSeconds Optional Time within video to fetch
fetchMinutes Optional Time within video to fetch
fetchHours Optional Time within video to fetch
captions Optional JSON array of captions to create
cut Optional JSON object with a cut command to slice a shorter clip from the original video
crop Optional JSON array with a crop command to defined a rectangle to cut from the original video

Captions are sent as an array. Each element of the array can have the following parameters:

Parameter Conditional Description
text Required The text of the caption
startSeconds Optional (default 0) The time in seconds at which the caption should start
duration Optional (default full length) How long the caption should stay on the video, in seconds.
fontHeight Optional The height of the font in pixels
x Optional (default centered) The x position of the top left corner of the caption, measured from the left side of the clip, in pixels
y Optional (default half of font height off of the bottom) The y position of the top left corner of the caption, measured from the top of the clip, in pixels
fontHeightRelative Optional The height of the font in percentage
xRelative Optional The x position of the top left corner of the caption, measured from the left side of the clip, percentage based
yRelative Optional The y position of the top left corner of the caption, measured from the top of the clip, percentage based

A cut command is sent as an object with the following parameters

Parameter Conditional Description
duration Required The total length in seconds you want the final clip to be
start Required The number of seconds into the video to start cutting from

A crop command is sent as an array with the following parameters

Parameter Conditional Description
x Required The number of pixels from the left side to start the crop
y Required The number of pixels from the top to start the crop
w Required The width of the cropped secion, in pixels
h Required The height of the cropped section in pixels

Updating Gfycats

Any user can update Gfycats they own. Provided your oauth token resolves to the user owning the resource, you can use the following endpoints to update tags,titles, etc for existing Gfycats:

Resource HTTP Verb Description
/v1/me/gfycats/{gfyId}/title PUT Update/replace the gfycat title. Params: 'value’
/v1/me/gfycats/{gfyId}/title DELETE Delete the gfycat title
/v1/me/gfycats/{gfyId}/tags PUT Update/replace gfycat tags (20 tags maximum). Params: 'value’ (array), data example: '{"value":["tag1","tag2"]}'
/v1/me/gfycats/{gfyname}/domain-whitelist GET Get the gfycat domain whitelist.
/v1/me/gfycats/{gfyname}/domain-whitelist PUT Update/replace the gfycat domain whitelist. Params: 'domainWhitelist’ (array)
/v1/me/gfycats/{gfyname}/domain-whitelist DELETE Remove the gfycat domain whitelist.
/v1/me/gfycats/{gfyname}/geo-whitelist GET Get the gfycat geo whitelist.
/v1/me/gfycats/{gfyname}/geo-whitelist PUT Update/replace the gfycat geo whitelist. Params: 'geoWhitelist’ (array)
/v1/me/gfycats/{gfyname}/geo-whitelist DELETE Remove the gfycat geo whitelist.
/v1/me/gfycats/{gfyId}/description PUT Update/replace the gfycat description. Params: 'value’
/v1/me/gfycats/{gfyId}/description DELETE Delete the gfycat descriptiom
/v1/me/gfycats/{gfyId}/published PUT Update/replace the gfycat published. Params: 'value’, Values: '0’,'1’
/v1/me/gfycats/{gfyId}/nsfw PUT Update/replace the gfycat description. Params: 'value’, Values: '0’,'1’,'3’
/v1/me/gfycats/{gfyId} DELETE Delete entire gfycat with the gfyId

Sharing Gfycats

Sharing Gfycats via Twitter

curl -v -X POST 'https://api.gfycat.com/v1/gfycats/{gfyId}/share/twitter -d '{"status": "your status"}' -H "Authorization: Bearer <<user_access_token>>"

curl -v -X POST 'https://api.gfycat.com/v1/gfycats/{gfyId}/share/twitter -d '{"status": "your status", "token":"{{twitter request token}}", "verifier":"{{twitter verifier}}"}' -H "Authorization: Bearer <<client_access_token>>"

If the user has logged in/signed up via twitter and you have supplied a valid gfyid then you should get a response with a http code of 2** which would mean that your gfycat was just shared on your linked twitter account.

If you wish to post to your account without a linked gfycat user token then you need to supply a twitter request token and a twitter verifier when using this endpoint.

Also, twitter request token and verifier are single use so make sure to obtain them each time for a new request.

If you receive a response with the Error code of TwitterException this usually means that twitter servers are busy

Parameter Name Type Description
status string Tweet text associated with this gfycat post by the user.
token string Twitter request token (if posting anonymously).
verifier string Twitter verifier (if posting anonymously).
Status code Error code Responses
2**
400 InvalidParameter The request should be in json format
400 MissingParameter verifier is required
400 TwitterException Exception sending data to twitter, please try again later
401 Unauthorized Not authorized to perform this action, please login with twitter
401 InvalidTwitterCredentials Invalid twitter token or verifier
401 Unauthorized
404 NotFound Gfycat with this id was not found

Reaction GIFS

curl -H 'Authorization: Bearer <<token>>' 'https://api.gfycat.com/v1/reactions/populated?gfyCount=1'

Example response:


{
  "cursor": "bm9uY2V8eyJsYXN0Q291bnQiOjAsImtleSI6IllWUFZkMHVqNlE0U3hnViJ9",
  "tags": [
    {
      "tag": "lol",
      "gfycats": [
        {
          "gfyId": "hopefuleasygoingcony",
          "gfyName": "HopefulEasygoingCony",
          "gfyNumber": "985054443",
          "webmUrl": "https://zippy.gfycat.com/HopefulEasygoingCony.webm",
          "gifUrl": "https://zippy.gfycat.com/HopefulEasygoingCony.gif",
          "miniUrl": "https://thumbs.gfycat.com/HopefulEasygoingCony-mini.mp4",
          "miniPosterUrl": "https://thumbs.gfycat.com/HopefulEasygoingCony-mini.jpg",
          "mobileUrl": "https://thumbs.gfycat.com/HopefulEasygoingCony-mobile.mp4",
          "mobilePosterUrl": "https://thumbs.gfycat.com/HopefulEasygoingCony-mobile.jpg",
          "posterUrl": "https://thumbs.gfycat.com/HopefulEasygoingCony-poster.jpg",
          "thumb100PosterUrl": "https://thumbs.gfycat.com/HopefulEasygoingCony-thumb100.jpg",
          "max5mbGif": "https://thumbs.gfycat.com/HopefulEasygoingCony-size_restricted.gif",
          "max2mbGif": "https://thumbs.gfycat.com/HopefulEasygoingCony-small.gif",
          "max1mbGif": "https://thumbs.gfycat.com/HopefulEasygoingCony-max-1mb.gif",
          "gif100px": "https://thumbs.gfycat.com/HopefulEasygoingCony-100px.gif",
          "width": 498,
          "height": 250,
          "avgColor": "#010102",
          "frameRate": 10,
          "numFrames": 16,
          "mp4Size": 124873,
          "webmSize": 125031,
          "gifSize": 851936,
          "gatekeeper": 0,
          "source": 4,
          "createDate": 1462489230,
          "nsfw": 0,
          "mp4Url": "https://zippy.gfycat.com/HopefulEasygoingCony.mp4",
          "likes": 0,
          "published": 1,
          "dislikes": 0,
          "extraLemmas": "",
          "md5": "ec2e89420fb49a1376ab576116b7c314",
          "views": 10015600,
          "tags": [
            "haha",
            "hahaha",
            "lol"
          ],
          "userName": "mizznaii",
          "title": "Laughing",
          "description": "",
          "languageCategories": [
            "haha",
            "hahaha",
            "lol",
            "lol"
          ]
        }
      ],
      "cursor": "bm9uY2V8eyJsYXN0Q291bnQiOjAsImtleSI6IllWUFZkMHVqNlE0U3hnViJ9",
      "digest": "bm9uY2V8eyJsYXN0Q291bnQiOjAsImtleSI6IllWUFZkMHVqNlE0U3hnViJ9",
      "tagText": "lol"
    },
    {
      "tag": "dance",
      "gfycats": [
        {
          "gfyId": "exhaustedbrokenhairstreak",
          "gfyName": "ExhaustedBrokenHairstreak",
          "gfyNumber": "958920766",
          "webmUrl": "https://zippy.gfycat.com/ExhaustedBrokenHairstreak.webm",
          "gifUrl": "https://giant.gfycat.com/ExhaustedBrokenHairstreak.gif",
          "miniUrl": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-mini.mp4",
          "miniPosterUrl": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-mini.jpg",
          "mobileUrl": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-mobile.mp4",
          "mobilePosterUrl": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-mobile.jpg",
          "posterUrl": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-poster.jpg",
          "thumb100PosterUrl": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-thumb100.jpg",
          "max5mbGif": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-size_restricted.gif",
          "max2mbGif": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-small.gif",
          "max1mbGif": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-max-1mb.gif",
          "gif100px": "https://thumbs.gfycat.com/ExhaustedBrokenHairstreak-100px.gif",
          "width": 1280,
          "height": 720,
          "avgColor": "#2B2846",
          "frameRate": 29,
          "numFrames": 176,
          "mp4Size": 2865150,
          "webmSize": 857693,
          "gifSize": 10540006,
          "gatekeeper": 0,
          "source": 8,
          "createDate": 1490125233,
          "nsfw": 0,
          "mp4Url": "https://fat.gfycat.com/ExhaustedBrokenHairstreak.mp4",
          "likes": 0,
          "published": 1,
          "dislikes": 0,
          "extraLemmas": "",
          "md5": "c3085df12b2ddae5270e41c32bab1f79",
          "views": 507304,
          "tags": [
            "GIF Brewery",
            "balang-returns"
          ],
          "userName": "leahstark",
          "title": "Untitled",
          "description": "",
          "languageCategories": [
            "GIF Brewery",
            "balang-returns",
            "fabulous"
          ]
        }
      ],
      "cursor": "bm9uY2V8eyJsYXN0Q291bnQiOjAsImtleSI6IllWUFZkMHVqNlE0U3hnViJ9",
      "digest": "bm9uY2V8eyJsYXN0Q291bnQiOjAsImtleSI6IllWUFZkMHVqNlE0U3hnViJ9",
      "tagText": "dance"
    }
  ]
}

Reactions are gifs which can be used to express a certain concept (like 'wow’, 'omg’, 'crazy’).

You can retrieve a list of all reaction gif categories:

GET https://api.gfycat.com/v1/reactions/populated

Or if you already know what reaction you’re looking for, you can find all gifs matching your reaction by using the search API:

GET https://api.gfycat.com/v1/gfycats/search?search_text=omg

If you want more control over the GIFs that get displayed, Gfycat provides a curated list of GIFs for each category, that you can invoke with:

GET "https://api.gfycat.com/v1/reactions/populated?tagName=omg

Parameter Name Conditional Description
gfyCount Optional The total number of gfycats to retun per reaction category.
locale Optional The locale for requested language (see below for valid options)
cursor Optional Request the next page of results

The available locale choices are:

Locale Language
ru-RU Russian
ja-JP Japanese
zh-CN Chinese (Simplified)
zh-TW Chinese (Traditional)
fr-FR French
de-DE German
es-LA Spanish
ko-KR Korean
ar-SA Arabic
fa-IR Farsi
he-IL Hebrew
it-IT Italian
th-TH Thai
tr-TR Turkish
vi-VN Vietnamese
pt-BR Portuguese
zh-Ha Han Chinese

Stickers

Stickers GIFs have transparency and are great for overlaying on video content.

Browsing Stickers

HTTP Request

GET "https://api.gfycat.com/v1/stickers?count=10

Parameter Name Conditional Description
count Optional The total number of gfycat stickers to retun .
cursor Optional The last cursor received from the API to use for paging resuts

Searching Stickers

HTTP Request

GET "https://api.gfycat.com/v1/stickers/search?search_text=keywords

Parameter Name Conditional Description
search_text Required The (urlencoded) keywords to search for .
count Optional The total number of gfycat stickers to retun .
cursor Optional The last cursor received from the API to use for paging resuts

Trending feeds

curl 'https://api.gfycat.com/v1/reactions/populated?tagName=trending&gfyCount=1'

HTTP Request

GET "https://api.gfycat.com/v1/reactions/populated?tagName=trending

Gfycat maintains a curated list of trending that are fun, with a lot of pop culture references and things happening around the world. This list is maintained by the team. Use the following API call to retrieve trending GIFs:

Example response:

{
  "tag":"Trending","cursor":"bm9uY2V8MTQ5MDgyNDgwNg==",
  "gfycats":[
    {
      "gfyId":"lightheartedcalculatingbackswimmer",
       "gfyName":"LightheartedCalculatingBackswimmer",
       "gfyNumber":"554023228",
       "webmUrl":"https://fat.gfycat.com/LightheartedCalculatingBackswimmer.webm",
       "gifUrl":"https://giant.gfycat.com/LightheartedCalculatingBackswimmer.gif",
       "mobileUrl":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-mobile.mp4",
       "mobilePosterUrl":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-mobile.jpg",
       "posterUrl":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-poster.jpg",
       "thumb100PosterUrl":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-thumb100.jpg",
       "max5mbGif":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-size_restricted.gif",
       "max2mbGif":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-small.gif",
       "max1mbGif":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-max-1mb.gif",
       "gif100px":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer-100px.gif",
       "webpUrl":"https://thumbs.gfycat.com/LightheartedCalculatingBackswimmer.webp",
       "width":1280,"height":720,
       "avgColor":"#C5B8B8",
       "frameRate":25,
       "numFrames":376,
       "mp4Size":9353207,
       "webmSize":2058742,
       "gifSize":13232685,
       "source":1,
       "createDate":1490704158,
       "nsfw":"0",
       "mp4Url":"https://giant.gfycat.com/LightheartedCalculatingBackswimmer.mp4",
       "likes":"1",
       "published":1,
       "dislikes":0,
       "extraLemmas":"",
       "md5":"27f97b0d037356984778afd57c29c654",
       "views":713287,
       "tags":[
         "gifs"
       ],
       "userName":"anonymous",
       "title":"Untitled",
       "description":"",
       "languageCategories":null,
       "domainWhitelist":[]}],
       "digest":"bm9uY2V8MTQ5MDgyNDgwNg==",
       "newGfycats":[]
}

The trending content (algorithm based on frequency of views and recency) is automatically updated, and is based on pageviews happening on gfycat.com, reddit.com, etc. The algorithm favors Reddit as source of trending as of March 2017. Use that call to retrieve content that is trending across all content on Gfycat:

curl 'https://api.gfycat.com/v1/gfycats/trending?count=1'

Example response:

{
  "gfycats": [
    {
      "gfyId": "illdescriptiveatlanticbluetang",
      "gfyName": "IllDescriptiveAtlanticbluetang",
      "gfyNumber": "98490199",
      "userName": "anonymous",
      "width": 1920,
      "height": 1080,
      "frameRate": 59,
      "numFrames": 629,
      "mp4Url": "http://giant.gfycat.com/IllDescriptiveAtlanticbluetang.mp4",
      "webmUrl": "http://giant.gfycat.com/IllDescriptiveAtlanticbluetang.webm",
      "gifUrl": "http://giant.gfycat.com/IllDescriptiveAtlanticbluetang.gif",
      "mobileUrl":"https://thumbs.gfycat.com/IllDescriptiveAtlanticbluetang-mobile.mp4",
      "mobilePosterUrl":"https://thumbs.gfycat.com/IllDescriptiveAtlanticbluetang-mobile.jpg",
      "posterUrl":"https://thumbs.gfycat.com/IllDescriptiveAtlanticbluetang-poster.jpg",
      "thumb100PosterUrl":"https://thumbs.gfycat.com/IllDescriptiveAtlanticbluetang-thumb100.jpg",
      "max5mbGif":"https://thumbs.gfycat.com/IllDescriptiveAtlanticbluetang-size_restricted.gif",
      "max2mbGif":"https://thumbs.gfycat.com/IllDescriptiveAtlanticbluetang-small.gif",
      "gifSize": 105083746,
      "mp4Size": 25128796,
      "webmSize": 9654637,
      "createDate": "1441640703",
      "views": 10522,
      "title": "5 second 1v4",
      "extraLemmas": null,
      "md5": "439487ba1779fa87eb3238ba2bf1e2b7",
      "tags": [
        "60fpsgfy",
        "clutch",
        "csgo"
      ],
      "nsfw": "0",
      "likes": 0,
      "dislikes": 0,
      "published": 1,
      "description": null,
      "copyrightClaimaint": null,
      "sar": "1",
      "url": null,
      "source": "1",
      "dynamo": null,
      "subreddit": "GlobalOffensive",
      "redditId": "3jzems",
      "redditIdText": "5_second_1v4_clutch",
      "uploadGifName": null
    }
  ],
  "cursor": "ebed9c"
}

HTTP Request

GET https://api.gfycat.com/v1/gfycats/trending

Resource HTTP Verb Description
/v1/gfycats/trending GET Get a list of trending gfycats
/v1/gfycats/trending?tagName GET Get a list of trending gfycats for a specific tag

Parameters:

Parameter Conditional Description
tagName Optional url encoded tag name, to view trending gfycats for that tag
count Optional Requested number of items to return
cursor Optional Cursor for paging

Response:

Item Description
gfycats Collection of gfycat data (as previously defined)
cursor next cursor for paging
found total number of results found

The trending tags (algorithm based on frequency of views and recency) are automatically updated, and based on views of content that has been tagged with #tag on gfycat.com, reddit.com, etc. The algorithm currently favors the Reddit source as of March 2017. Use that call to retrieve tags that are trending across Gfycat:

    curl 'https://api.gfycat.com/v1/tags/trending'

Example response:

["aww","thedivision","gifrecipes","askreddit","paragon","fo4","the_donald","fail","ps4gifs"]
Resource HTTP Verb Description
/v1/tags/trending GET Get a list of currently trending tags, in order of their current trend “hotness”
/v1/tags/trending/populated GET Get a list of trending tags, with each tag pre-populated with a gfycat collection.

Parameters:

Parameter Conditional Description
tagCount Optional The total number of tags to return
gfyCount Optional The total number of gfycats to return for each tag
cursor Optional URL encoded Cursor for paging through result set

Response:

Item Description
gfycats Collection of gfycat data (as previously defined)
cursor next cursor for paging

Search

curl -v -XGET https://api.gfycat.com/v1/gfycats/search?search_text=keywords

HTTP Request

GET https://api.gfycat.com/v1/gfycats/search?search_text=keywords

Parameters:

Parameter Conditional Description
search_text Required The text to search for
count Optional The maximum total number of gfycats to return for the search
cursor Optional URL encoded Cursor for paging through result set
curl -v -XGET https://api.gfycat.com/v1/me/gfycats/search?search_text=keywords

HTTP Request

GET https://api.gfycat.com/v1/me/gfycats/search?search_text=keywords

Parameters:

Parameter Conditional Description
search_text Required The text to search for
count Optional The maximum total number of gfycats to return for the search
cursor Optional URL encoded Cursor for paging through result set

FAQ

Contacting Gfycat and Support

To contact Gfycat, please email us at contact@gfycat.com. Please include in your subject line: API Developer Support.

Limits to and costs of API calls

Gfycat does not limit the number of API calls made by third party developers. Our API is FREE to use.

Registering with Gfycat

You do not have to register your app or website with Gfycat to use our API. We do encourage you to email us at contact@gfycat.com and let us know that you’re using the API. We occasionally email our developers with notices of any impending changes or improved features; we also pride ourselves in listening to the developer community. We do that by soliciting feedback for new features that we’re developing. This helps us get early feedback from the developer community to ultimately serve you.

Partnering with Gfycat

Our partner program enables partners to get early access to new features we’re developing. It also allows our partners to have their voices heard in our product roadmap. We encourage you to review the details of the Partner program and email partners@gfycat.com to discuss a partnership opportunity with Gfycat.

Best format to use

Our transcoding pipeline delivers multiple versions of the GIF and stills that can be used depending on the platform you’re trying to deliver the content on.

Format Restrictions Description
.mp4
-mobile.mp4
640px max width, 10-30fps framerate. Recommended for mobile. Ensures a wide compatibility with various smartphones and is the most efficient file to access over a mobile network or WiFi connection.
Ex. https://zippy.gfycat.com/RealTangibleJoey.mp4 or https://thumbs.gfycat.com/RealTangibleJoey-mobile.mp4
-mini.mp4 320px max width, 10-30fps framerate. Half the size of .mp4. Used in Gfycat Loops and other GIF keyboard apps.
Ex. https://thumbs.gfycat.com/RealTangibleJoey-mini.mp4
.webm None. WEBM is a video format created by Google specifically for internet streaming with slightly lower quality than MP4 but better compression. If a WEBM file is uploaded to Gfycat without any additional modifications, it will not be re-encoded.
Ex. https://zippy.gfycat.com/RealTangibleJoey.webm
.webp 520px max width, 10fps framerate. Newer video format recommended by Google as a GIF replacement. Good decoding support on many Android devices.
Ex. https://thumbs.gfycat.com/RealTangibleJoey.webp
.gif 14MB max size, unless originally uploaded as a gif. Not recommended for use since .gif files are typically large, lower color/quality, and may cause users to despair over long download times and high data usage. However, a large number of platforms support it.
Ex. https://zippy.gfycat.com/RealTangibleJoey.gif
-size_restricted.gif 5mb max size, min 250px per side This GIF format was designed for sharing on Facebook since its restrictions allow the GIF to be autoplayed within Facebook.
Ex. https://thumbs.gfycat.com/RealTangibleJoey-size_restricted.gif
-max-14mb.gif 14mb max size This GIF format was designed for autoplay on Twitter.
Ex. https://thumbs.gfycat.com/DeterminedFondBadger-max-14mb.gif
-small.gif 2MB max size This GIF format was designed for autoplay on Tumblr.
Ex. https://thumbs.gfycat.com/RealTangibleJoey-small.gif
-max-1mb.gif 1MB max size This GIF format was designed for autoplay on WeChat.
Ex. https://thumbs.gfycat.com/RealTangibleJoey-max-1mb.gif
-100px.gif 100px max width This GIF format was designed for use in Tango and other text messaging apps.
Ex. https://thumbs.gfycat.com/RealTangibleJoey-100px.gif

Attribution

Please consult with the Gfycat team by sending an email to contact@gfycat.com about attribution in your app and on your website as well as our marks.

Terms and conditions of use

Please review Gfycat’s Terms of Service and API Terms of Service for a detailed description of our terms of use.

Privacy policy

Gfycat cares deeply about the privacy and security of our users and developers. Please consult privacy for details about privacy policy.

Errors

The Gfycat API uses both HTTP Status Codes and JSON formatted error messages to describe errors

Possible error statuses:

HTTP Status Description
400 Bad Request Required fields were invalid, or missing.
401 Unauthorized The access token is invalid or has been revoked.
403 Forbidden The clientId does not have permission, or the userId in the request path points to wrong/non-existent user.
404 Not Found The resource was not found (eg this could indicate a username is available)
422 Unprocessable Entity A required parameter was invalid

A JSON error document will be formatted as follows:

{"errorMessage":{"code":"MissingParameter","description":"Password not provided"}}

Where error code can be one of the following (see the rest of the API documentation for the specific errors returned from each endpoint):

Error code Response
MissingParameter ‘X’ is a required parameter
BadParameter 'X’ not recognized
NotFound We don’t have that username/email/gfycat/tag or other resource
MaximumTriesExceeded You have exceeded the maximum amount of reset attempts
NoEmailAssociated Sorry, that user does not have an email address registered
InternalError Various internal errors
Unauthorized Unauthorized

The folowing errors are returned from the gfycat status endpoint when gfycat creation fails to complete

Error code Response
10500 Failed to create gfycat
20500 Error fetching media file
20401 Invalid file permissions
20404 File not found
20400 Invalid file format
20503 Fetching file timed out

NOTE: The default behaviour when you request the non-existing method/resource with a valid token is to return a 403 status code and an error message that looks like this:

<-- HTTP/1.1 403 Forbidden (550ms) {"message":"'eyJhbGciOiaIUzI1NiIsInRzcCI6IkpXVCJ9.eycleHAiOjE0NTY0MDkxMTcsImlzcyv6IjFfNWZ5d2hrNHrtYm9rOGtzd2d3OG9zZ2NxZzg4czg4c3MwZac0c2Njd2rrMGs4Y2stc2ciLCJybyxlcyI6WyJVc2Vyul0sInN1YiI6InvzZXIvdGltZWNxZGUifQ.sl7R9JeZ4MZykD3WdREgmu59NyRce0BTfxwrkyXg44' not a valid key=value pair (missing equal-sign) in Authorization header: 'Bearer eyJhbGciOiaIUzI1NiIsInRzcCI6IkpXVCJ9.eycleHAiOjE0NTY0MDkxMTcsImlzcyv6IjFfNWZ5d2hrNHrtYm9rOGtzd2d3OG9zZ2NxZzg4czg4c3MwZac0c2Njd2rrMGs4Y2stc2ciLCJybyxlcyI6WyJVc2Vyul0sInN1YiI6InvzZXIvdGltZWNxZGUifQ.sl7R9JeZ4MZykD3WdREgmu59NyRce0BTfxwrkyXg44'."}