Getting Started

Please note: This guide refers to the overview and authentication of the Moz API for requesting Brand Authority data. For documentation regarding the Moz API for links data, please see our Moz API — Links documentation.

This guide covers the authentication, request format, and common errors for the Moz API for Brand Authority^tm.

Quick Links

• Signing Up and Getting Started
• Credentials
• API Location
• Authentication
• Request Format
• Successful Response Format
• Error Response Format
• Common Errors
• Overview of API Endpoint Methods

Whether you are interested in a free or paid plan, we do require valid credit card information to authenticate your account. Please note: The API key sign-up process is the same for free and paid plans.

Already a Moz Pro subscriber? You’ve already got access! Jump ahead to the Credentials section.

1. To get started, follow these steps:
2. Log into your Moz account — moz.com/users/login
3. Head to the API product page and select Get Connected
4. Select Try it free! or select a paid plan
5. Enter your payment details (A credit card is required for a free API plan)
6. Set up your API Credentials (see below for more information)

Moz API access can be managed through the API Dashboard page, a hub where you can manage authentication tokens and review your quota usage for requesting Brand Authority data.

1. Access the dashboard at https://moz.com/api/dashboard
2. Select + Add Token to generate a new token for API usage
3. Enter a description for your token and click Create
4. You should now see your new token in the API Tokens section of the dashboard

The number of API Tokens you can generate will depend on your subscription level.

All API endpoints within the Moz API for Brand Authority use the following base URL: https://api.moz.com/jsonrpc

The endpoint you are looking to request data from will need to be specified under the method field in the body of your JSON request. See the Request Format section below for details on how best to structure your call.

The token generated in the above steps simplifies the authentication process to access Moz API. When structuring your request, all you need to do is add your token as a header value with the key `x-moz-token`.

All requests are structured in JSON-RPC format, and must be sent as POST requests to the base API URL, with the endpoint name specified in the “method” field of the POST body. This format provides greater consistency in the structure of requests made to the Moz API, using the members outlined below for every call. The following example illustrates the format for these members:

“jsonrpc” — A string specifying the version of the JSON-RPC protocol. MUST be exactly “2.0”.

“id” — A unique request identifier established by the client. It MUST contain a unique string at least 24 characters long. It may ONLY contain uppercase letters, lowercase letters, numbers, and dashes. It is suggested that clients use a V4 UUID for these identifiers.

“method” — A string containing the name of the method to be invoked. Methods will be detailed in each endpoint’s respective documentation.

“params” — A structured value that holds the parameter values to be used during the invocation of the method. As parameters are specific to endpoints, you will find necessary and optional parameters also within endpoint documentation.

All successful responses follow the standard JSON-RPC format and are returned with HTTP status code 200. This response is expressed as a single JSON object with the following members:

“jsonrpc” — A string specifying the version of the JSON-RPC protocol. MUST be exactly “2.0”.

“id” — An id value that MUST match the same value of the id member in the request object.

“result” - REQUIRED on success. This member will contain the values you’re looking to retrieve, specific to each endpoint, and documented accordingly.

“error” — REQUIRED if there was an error with the call. See below for more details.

When an RPC call encounters an error, the response object MUST contain the error member with a value that is an object with the following members:

“code” — A number that indicates the error type that occurred.

“status” — The HTTP status code providing specification against the error received.

“message” — A string providing a short description of the error.

“data” — A primitive value that may contain additional information about the error, if relevant.

Please note that any call resulting in an error message will not decrease your quota

The table below lists standard code designations specific to JSON-RPC:

Additionally, here are some of the specific errors you may encounter when working with the Moz API

• Authentication
  Message: Missing or invalid authentication
  HTTP Status Code: 401
  JSON-RPC Status Code: -32651

• Internal Server
  Message: An unexpected has occurred
  HTTP Status Code: 500
  JSON-RPC Status Code: -32602

• Duplicate Request
  Message: That request ID has already been used
  HTTP Status Code: 400
  JSON-RPC Status Code: -32656

• Invalid Request
  Message: The request is invalid
  HTTP Status Code: 400
  JSON-RPC Status Code: -32654

• Invalid Method
  Message: Method not found
  HTTP Status Code: 400
  JSON-RPC Status Code: -32601

• Missing Request
  Message: Object not found
  HTTP Status Code: 404
  JSON-RPC Status Code: -32655

• Incomplete Request
  Message: Retry Request
  HTTP Status Code: 409
  JSON-RPC Status Code: -32659

• Run Failure
  Message: An error occurred running the action
  HTTP Status Code: 400
  JSON-RPC Status Code: -32653

• Non-Action Error
  Message: Unhandled error
  HTTP Status Code: 500
  JSON-RPC Status Code: -32602

• Invalid Parameters
  Message: A value you provided was invalid
  HTTP Status Code: 400
  JSON-RPC Status Code: -32652

The Moz API for Brand Authority consists of 3 primary endpoint methods: Fetch, Generate, and Async. Below is a diagram of how these methods work together.