Overview & Authentication - Moz API for Link Data V2

Please note: This guide refers to the overview and authentication of Moz Links API V2. If you are using Moz Links API V1, please see our V1 Authentication guide.

This guide covers authentication and request format for the Moz Links API V2. It also covers common errors and response formats.

Quick Links

• API Location
• Credentials
• Authentication
• Request Format
• Successful Response Format
• Error Response Format
• Common Errors
• Versioning
• Getting Started Cheat Sheet

All links v2 API endpoints use the following base URL: https://lsapi.seomoz.com/v2/

The endpoint you are looking to request data from will need to be added to the base URL. For example, if you are looking to call data from the Anchor Text endpoint, the URL would be https://lsapi.seomoz.com/v2/anchor_text

Each endpoint URL can be verified within the Making Calls section of the Help Hub on the corresponding page.

To access the Links v2 API, use your Moz API credentials API Token. To generate a token, follow these steps:

1. Access the Moz API 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 token generated during sign-up 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`.

Alternative (legacy) authentications:

• Basic Auth over HTTPS

  If you were a user of the Moz API before March 2024, you can authenticate requests via Basic Auth over HTTPS. Use your 'Access ID' as a username, and your 'Secret Key' as a password. If you are a legacy subscriber, this will be noted with a Legacy Token tag in your usage dashboard. Click Show legacy credentials to find your access ID and Secret Key.Mozscape Signed Authentication

• Moz Links API v1 Signed Authentication

  For clients unable to connect over HTTPS, we also support Legacy Moz Links API v1 Signed Authentication over HTTP (see here.)

All requests are structured as JSON, and must be sent as POST requests to their respective endpoints. The specific request syntax and parameters available for each endpoint are documented on their respective pages.

If you use Postman for making API calls, you can use the link here to import the Moz Links V2 API collection. This will provide real examples of each endpoint’s call format - you will just need to enter your Access ID and Secret Key within the Authentication tab and edit the body to request the data you’re looking for.

All successful responses are structured as JSON and are returned with HTTP status code 200. The specific syntax and elements for each endpoint are documented on their respective pages.

All error responses are structured as JSON and are returned with an HTTP status code in the 4xx-5xx range.

The syntax for error responses is shared between all endpoints and is as follows:

{ "name": "string", "message": "string"}

• name

  A short name for the error that is intended to remain fixed over time and be interpreted by programs.

  Type: string

• message

  A description of the error that is intended to change over time and be interpreted by humans.

  Type: string

• Bad Request

  Message: One or more input parameters are invalid.
  HTTP Status Code: 400

• Not Authorized

  Message: Your authentication failed.
  HTTP Status Code: 401

• Not Authorized

  Message: Your authentication has expired.
  HTTP Status Code: 401

• Not Authorized

  Message: Your monthly row limit reached.
  HTTP Status Code: 401

• Forbidden

  Message: Unrecognized API method.
  HTTP Status Code: 403

• Forbidden

  Message: This account has been banned from this API.
  HTTP Status Code: 403

• Forbidden

  Message: This account has been banned from Moz's APIs.
  HTTP Status Code: 403

• Too Many Requests

  Message: This request exceeds the limit allowed by your current plan.
  HTTP Status Code: 429

• Message: You are producing the error: URL must be ascii only

  To resolve: Use the punycode version of the URL

The current version of the Links API is 2. This version is incremented when there is a breaking change to an endpoint's behavior so we can maintain backwards compatibility. Additional fields that do not change the meaning of existing fields and additional optional query parameters that do not change the default behavior are not considered breaking changes.