RESTful API Reference

Note: You can find our OpenAPI Spec in YAML format here if you want to access the API from applications that support OpenAPI.

Authentication

All API endpoints require authentication using an API key. The API key should be included in the X-API-Key header of each request.

Project Names and URLs

Project names will be sanitized to remove any special characters or HTML tags. If no project name is provided, a fallback name will be generated using the format
“noname_” followed by an MD5 hash of the submitted URLs. URLs will be validated and must start with either “http://” or “https://”. Invalid URLs will be discarded.

Error Responses

If an error occurs, the API will return an appropriate HTTP status code along with an error message in the response body. Possible error codes include:

• 400 Bad Request – The request was malformed or missing required parameters.
• 401 Unauthorized – The API key is missing or invalid.
• 403 Forbidden – The API key is valid but does not have permission to access the requested resource.
• 404 Not Found – The requested resource (e.g., project) does not exist.
• 429 Too Many Requests – The rate limit for API requests has been exceeded.
• 500 Internal Server Error – An unexpected error occurred on the server.

RESTful API Endpoints

List All Projects

Endpoint: GET https://rapidurlindexer.com/wp-json/api/v1/projects/list

Retrieves a list of all projects for the authenticated user, ordered by creation date (newest first).

Arguments:

• None required. Authentication via X-API-Key header.

Successful Response (200 OK):

{
    "success": true,
    "projects": [
        {
            "id": 123,
            "name": "My Project",
            "status": "submitted",
            "submitted_urls": 100,
            "indexed_urls": 75,
            "created_at": "2024-01-20T10:00:00Z"
        },
        {
            "id": 122,
            "name": "Another Project",
            "status": "completed",
            "submitted_urls": 50,
            "indexed_urls": 48,
            "created_at": "2024-01-19T15:30:00Z"
        }
    ]
}

Response Fields:

• id (integer): Unique identifier of the project
• name (string): Name of the project
• status (string): Current status of the project (pending/submitted/completed/failed/refunded)
• submitted_urls (integer): Total number of URLs submitted in the project
• indexed_urls (integer): Number of URLs successfully indexed
• created_at (string): Project creation timestamp in RFC3339 format

Error Response (401 Unauthorized):

{
    "message": "Invalid API key"
}

This endpoint is useful for retrieving an overview of all your projects and their current status without having to query each project individually.

Submit a New Project

Endpoint: POST https://rapidurlindexer.com/wp-json/api/v1/projects

Request Body:

{
    "project_name": "My Project",
    "urls": ["http://example.com", "http://example.org"],
    "notify_on_status_change": true
}

Arguments:

• project_name (string, required): The name of your project.
• urls (array of strings, required): An array of URLs to be indexed. Each URL must start with “http://” or “https://”.
• notify_on_status_change (boolean, optional, default: false): If set to true, you will receive email notifications when the project status changes.

Successful Response (201 Created):

{
    "message": "Project created successfully",
    "project_id": 123
}

Error Responses:

400 Bad Request
{
    "message": "Invalid project name or URLs"
}

401 Unauthorized
{
    "message": "Invalid API key"
}

403 Forbidden
{
    "message": "Insufficient credits"
}

Get Project Status

Endpoint: GET https://rapidurlindexer.com/wp-json/api/v1/projects/{project_id}

Arguments:

• project_id (integer, required): The ID of the project you want to check.

Successful Response (200 OK):

{
    "project_id": 123,
    "project_name": "My Project",
    "status": "submitted",
    "submitted_links": 2,
    "processed_links": 1,
    "indexed_links": 1,
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:05:00Z"
}

Possible Status Values:

• pending: The project has been created but not yet submitted for indexing.
• submitted: The project has been submitted and indexing is in progress.
• completed: The indexing process has been completed.
• failed: The indexing process failed. Credits have been refunded.
• refunded: Some URLs were not indexed within 14 days, and credits have been automatically refunded.

Error Response (404 Not Found):

{
    "message": "Project not found"
}

Download Project Report

Endpoint: GET https://rapidurlindexer.com/wp-json/api/v1/projects/{project_id}/report

Arguments:

• project_id (integer, required): The ID of the project for which you want to download the report.

Successful Response (200 OK):

Returns a CSV file with the following format:

URL,Status
http://example.com,Indexed
http://example.org,Not Indexed

Error Response (404 Not Found):

{
    "message": "Project report not available"
}

Get Credit Balance

Endpoint: GET https://rapidurlindexer.com/wp-json/api/v1/credits/balance

Successful Response (200 OK):

{
    "credits": 100
}

Error Response (401 Unauthorized):

{
    "message": "Invalid API key"
}

Rate Limiting

API requests are limited to 100 requests per minute per API key. If you exceed this limit, you’ll receive a 429 Too Many Requests response.

OpenAPI 3.1 Specification (Swagger)

openapi: 3.1.0
info:
  title: Rapid URL Indexer
  description: "API for submitting URLs to Rapid URL Indexer (https://rapidurlindexer.com/) for indexing and monitoring their status. Requires API key authentication via X-API-Key header for all endpoints."
  version: '1.0.1'

servers:
  - url: https://rapidurlindexer.com/wp-json
    description: Production API

security:
  - apiKeyAuth: []

paths:
  /api/v1/projects/list:
    get:
      summary: List all projects
      operationId: listProjects
      description: Retrieves a list of all projects for the authenticated user, ordered by creation date (newest first)
      responses:
        '200':
          description: List of projects retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  projects:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique identifier of the project
                        name:
                          type: string
                          description: Name of the project
                        status:
                          type: string
                          enum: [pending, submitted, completed, failed, refunded]
                          description: Current status of the project
                        submitted_urls:
                          type: integer
                          description: Total number of URLs submitted in the project
                        indexed_urls:
                          type: integer
                          description: Number of URLs successfully indexed
                        created_at:
                          type: string
                          format: date-time
                          description: Project creation timestamp in RFC3339 format
              examples:
                default:
                  value:
                    success: true
                    projects:
                      - id: 123
                        name: "My Project"
                        status: "submitted"
                        submitted_urls: 100
                        indexed_urls: 75
                        created_at: "2024-01-20T10:00:00Z"
                      - id: 122
                        name: "Another Project"
                        status: "completed"
                        submitted_urls: 50
                        indexed_urls: 48
                        created_at: "2024-01-19T15:30:00Z"
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/projects:
    post:
      summary: Submit new project for indexing
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
            examples:
              default:
                value:
                  project_name: "My Test Project"
                  urls: ["https://example.com", "https://example.org"]
                  notify_on_status_change: true
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
              examples:
                default:
                  value:
                    message: "Project created successfully"
                    project_id: 123
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/projects/{project_id}:
    get:
      summary: Get project status
      operationId: getProjectStatus
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Project status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatus'
              examples:
                default:
                  value:
                    project_id: 123
                    project_name: "My Test Project"
                    status: "submitted"
                    submitted_links: 2
                    processed_links: 1
                    indexed_links: 1
                    created_at: "2024-01-20T10:00:00Z"
                    updated_at: "2024-01-20T10:05:00Z"
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/projects/{project_id}/report:
    get:
      summary: Download project report
      operationId: getProjectReport
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Project report in CSV format
          content:
            text/csv:
              schema:
                type: string
              examples:
                default:
                  value: |
                    URL,Status
                    https://example.com,Indexed
                    https://example.org,Not Indexed
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/credits/balance:
    get:
      summary: Get credit balance
      operationId: getCreditBalance
      responses:
        '200':
          description: Current credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalance'
              examples:
                default:
                  value:
                    credits: 100
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    ProjectRequest:
      type: object
      required:
        - project_name
        - urls
      properties:
        project_name:
          type: string
          description: Project name (will be sanitized)
        urls:
          type: array
          description: URLs to be indexed
          items:
            type: string
            format: uri
            pattern: '^https?://'
          minItems: 1
        notify_on_status_change:
          type: boolean
          default: false

    ProjectResponse:
      type: object
      properties:
        message:
          type: string
        project_id:
          type: integer

    ProjectStatus:
      type: object
      properties:
        project_id:
          type: integer
        project_name:
          type: string
        status:
          type: string
          enum: [pending, submitted, completed, failed, refunded]
          description: |
            - pending: Created but not submitted
            - submitted: Indexing in progress
            - completed: Indexing finished
            - failed: Indexing failed (credits refunded)
            - refunded: Some URLs not indexed within 14 days
        submitted_links:
          type: integer
        processed_links:
          type: integer
        indexed_links:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreditBalance:
      type: object
      properties:
        credits:
          type: integer

    Error:
      type: object
      properties:
        message:
          type: string

  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                message: "Invalid project name or URLs"

    Unauthorized:
      description: Invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                message: "Invalid API key"

    Forbidden:
      description: Insufficient credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                message: "Insufficient credits"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                message: "Project not found"