Overview & Authentication for Links API V2

Please note: This guide refers to the overview and authentication of Links API V2. If you are using 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

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 Links API credentials ('Access ID' and 'Secret Key'). For existing API users, these credentials are the same ones you use for the Mozscape API.

• Basic Auth over HTTPS

  The easiest way to authenticate requests is via Basic Auth over HTTPS. Use your 'Access ID' as a username, and your 'Secret Key' as a password.

• Mozscape Signed Authentication

  For clients unable to connect over HTTPS, we also support Legacy Mozscape 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.