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": ["https://example.com", "https://example.org"],
    "notify_on_status_change": false
}

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",
    "urls": [
        "https://example.com/page1",
        "https://example.com/page2"
    ],
    "submitted_links": 2,
    "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.
• Accept (header, optional): Response format. Use application/json for JSON format, defaults to text/csv for CSV format.

Successful Response (200 OK):

CSV Format (default):

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

JSON Format (when Accept: application/json header is provided):

{
  "project_id": 123,
  "project_name": "My Test Project",
  "total_urls": 2,
  "urls": [
    {
      "url": "https://example.com",
      "status": "indexed"
    },
    {
      "url": "https://example.org",
      "status": "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.3'

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: false
      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
      description: Retrieves detailed status information for a specific project, including submitted URLs and indexing progress
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the project
      responses:
        '200':
          description: Project status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatus'
              examples:
                default:
                  value:
                    project_id: 123
                    project_name: "My Test Project"
                    status: "submitted"
                    urls: 
                      - "https://example.com"
                      - "https://example.org"
                    submitted_links: 2
                    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
      description: |
        Returns indexing report with detailed URL status information.
        Supports both CSV and JSON formats via Accept header.
        Reports are available 96 hours (4 days) after project creation.
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the project
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            enum: [text/csv, application/json]
            default: text/csv
          description: Preferred response format (defaults to CSV for backward compatibility)
      responses:
        '200':
          description: Project report in requested format
          content:
            text/csv:
              schema:
                type: string
              examples:
                default:
                  value: |
                    URL,Status
                    https://example.com,Indexed
                    https://example.org,Not Indexed
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectReport'
              examples:
                default:
                  value:
                    project_id: 123
                    project_name: "My Test Project"
                    total_urls: 2
                    urls:
                      - url: "https://example.com"
                        status: "indexed"
                      - url: "https://example.org"
                        status: "not_indexed"
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '425':
          description: Report not yet available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                time_not_elapsed:
                  value:
                    message: "Report not yet available. Initial indexation report will be ready after 4 days. Please check back later."
                data_processing:
                  value:
                    message: "Report not yet available. Indexation data is still being processed. Please try again later."

  /api/v1/credits/balance:
    get:
      summary: Get credit balance
      operationId: getCreditBalance
      description: Retrieves the current credit balance for the authenticated user
      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)
          minLength: 1
          maxLength: 255
        urls:
          type: array
          description: URLs to be indexed (each must start with http:// or https://)
          items:
            type: string
            format: uri
            pattern: '^https?://'
          minItems: 1
          maxItems: 9999
        notify_on_status_change:
          type: boolean
          default: false
          description: Whether to receive email notifications when project status changes

    ProjectResponse:
      type: object
      properties:
        message:
          type: string
          description: Success message
        project_id:
          type: integer
          description: Unique identifier of the created project

    ProjectStatus:
      type: object
      properties:
        project_id:
          type: integer
          description: Unique identifier of the project
        project_name:
          type: string
          description: Name of the project
        status:
          type: string
          enum: [pending, submitted, completed, failed, refunded]
          description: |
            Current project status:
            - pending: Created but not yet submitted to indexing provider
            - submitted: Indexing in progress
            - completed: Indexing process finished
            - failed: Indexing failed (credits refunded)
            - refunded: Some URLs not indexed within 14 days (partial refund issued)
        urls:
          type: array
          description: List of URLs submitted for indexing
          items:
            type: string
            format: uri
        submitted_links:
          type: integer
          description: Total number of URLs submitted
          minimum: 0
        indexed_links:
          type: integer
          description: Number of URLs successfully indexed
          minimum: 0
        created_at:
          type: string
          format: date-time
          description: Project creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp

    ProjectReport:
      type: object
      properties:
        project_id:
          type: integer
          description: Unique identifier of the project
        project_name:
          type: string
          description: Name of the project
        total_urls:
          type: integer
          description: Total number of URLs in the report
          minimum: 0
        urls:
          type: array
          description: Detailed status for each URL
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
                description: The submitted URL
              status:
                type: string
                enum: [indexed, not_indexed]
                description: Indexing status of the URL

    CreditBalance:
      type: object
      properties:
        credits:
          type: integer
          description: Current credit balance
          minimum: 0

    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message describing what went wrong

  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication (found in "My Projects" section)

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_data:
              value:
                message: "Invalid project name or URLs"
            validation_error:
              value:
                message: "All URLs must start with http:// or https://"

    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_key:
              value:
                message: "API key is missing"
            invalid_key:
              value:
                message: "Invalid API key"

    Forbidden:
      description: Insufficient credits or account suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            insufficient_credits:
              value:
                message: "Insufficient credits"
            account_suspended:
              value:
                message: "Account suspended"

    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            project_not_found:
              value:
                message: "Project not found or access denied"